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CHAPTER 1 

Extending Dreamweaver Overview 



This book covers the advanced capabilities you get when you extend 
Dreamweaver. Extensions are objects, commands, menu commands, panels, data 
translators, Property inspectors, reports, and behaviors that you create using the 
Dreamweaver application programming interface (API). This book helps you 
write your own extensions by providing information about how to program each 
type of extension and by explaining the Dreamweaver API. Read this chapter to 
find out the requirements involved in writing extensions, as well as for an 
overview of extensions. 



Customizing or extending? 

Before you begin reading this book, take a look at "Customizing Dreamweaver," 
in the Dreamweaver 4 user guide. This chapter provides procedures for changing 
Dreamweaver panels, menus, dialog boxes, and HTML formats. It also explains 
some of the basics involved in extending Dreamweaver functionality, including 
how to edit Dreamweaver commands and how to add third-party tags. 

When you're ready to extend Dreamweaver — to create your own objects, 
commands, menu commands, panels, Property inspectors, reports, data 
translators, and behaviors — read this book. 

Note: Before you begin writing extensions, refer to "Using Dreamweaver" for more 
information on how to install Dreamweaver. 
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Reading this book 



This book describes the supported Dreamweaver API. Dreamweaver extensions 
are written in JavaScript. The scripts can perform edits on the document using 
a Document Object Model (DOM), and they can call C code that you have 
packaged in a DLL. You should have some experience in creating Web pages with 
Dreamweaver. Also, you should be familiar with the languages you use to extend 
Dreamweaver, either JavaScript or C. 

The following sections describe the chapters in the order they appear in this book. 



Looking at the big picture 

• This chapter outlines the Dreamweaver extension architecture and how to 
begin creating extensions. 

• "The Document Object Model and JavaScript in Extensions" explains the 
Dreamweaver Document Object Model (DOM) and how to access and 
display data from the user's document through JavaScript calls to the 
documents DOM. 



Developing extensions 

• "Objects" describes object extensions, details the object API, explains how the 
object file works, and provides examples. 

• "Commands" explains how commands work and how to add your command 
to a menu. This chapter also details the commands API and provides examples. 

• "Menu Commands" explains how menu commands work and how to add your 
command to a menu. This chapter also details the menu commands API and 
provides examples. 

• "Reports" explains how to extend the set of prewritten reports shipped with 
Dreamweaver. 

• "Debugger" explains how to extend the JavaScript debugger, create a debug 
version of the users document, step through the JavaScript code, and 
return errors. 

• "Property Inspectors" describes how to create custom inspectors, details 
the Property inspector API, explains how the inspectors works, and 
provides examples. 

• "Floating Panels" describes how floating panel extensions work, details the 
floating panel API, and provides examples. 

• "Behaviors" explains how to write a behavior action, details the behavior API, 
explains how behaviors work, and provides examples. 
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Working with other products and utilities 

• "Fireworks Integration API" explains how to launch and execute commands in 
Fireworks from Dreamweaver. 

• "Flash Objects" explains how to create and modify Flash Object files. 

• "The Design Notes API" describes the JavaScript and C functions that add file 
information, such as document history and association, to Design Notes. 

• "The File I/O API" explains common file manipulation methods available 
through the DWf i 1 e object. 

• "The HTTP API" explains how to get and post files to an HTTP server using 
the DWHttp object. 

• "The Source Control API" explains how to integrate source control application 
with Dreamweaver. 

• "Data Translators" describes how translators work, details the data translator 
API, and how to create a translator, lock tags, and attributes. 

• "C-Level Extensibility" explains how to create an interface between your 
C libraries and the Dreamweaver JavaScript API. 

• "The Dreamweaver JavaScript API" is your reference guide to the main 
Dreamweaver API. It covers the JavaScript API according to functionality. 



The extension architecture 

The open nature of the Dreamweaver architecture enables you to modify virtually 
every aspect of Dreamweaver. How you interface with the product depends on the 
type of extension you write. This section explains the types of extension you can 
create. For additional information regarding the Dreamweaver architecture, read 
"The Document Object Model and JavaScript" on page 13, which explains the 
Dreamweaver DOM and how JavaScript works with extensions. 



Extension types 

A simple way to extend Dreamweaver is to add a button on the object panel. 
Then, each time the user drags that object onto the Design view of the Document 
window, Dreamweaver inserts the code associated with the object into the 
HTML. You create this kind of select-to-insert functionality by writing an object. 

The following list represents the different ways you can extend Dreamweaver. You 
can extend Dreamweaver in one or all of the following ways: add objects to the 
Objects panel, add commands that insert or rearrange HTML tags and attributes, 
create your own floating panel, add client-side JavaScript behaviors, or write 
translators that convert specialized code into standard HTML. 
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The different extension types can be summarized as follows: 



1 Object — Also known as an "insert-only" extension. You write this type of 
extension to add a new object to the Objects panel. You create this type of 
extension by writing an HTML file that contains the code to be inserted 
into the document. It can also contain a form that gathers input from the 
user and JavaScript that processes the input. You place the HTML file in 
the Configuration/Objects/*folder (where * is a wildcard representing any 
subfolder) along with an icon in GIF format, and the extension appears on 
the Objects panel. 

2 Command — A command is a menu item that invokes a script. When you 
create this type of extension, you add a new menu item to Dreamweaver. 
To create a command, you create a file that implements the functions in the 
commands API (see "Commands" on page 37). If you want the command to 
appear in the "Commands" menu, just install the file in the Configuration/ 
Commands folder. If you want the command to appear elsewhere in the menu 
system, you can customize the menu.xml file. When the user pops up a menu, 
the command can specify whether its menu item is grayed out or not. 

3 Panel — Dreamweaver has panels that provide information about the current 
document and the current selection. You can add your own floating panel that 
interacts with the selection, the document, or the task, or that simply displays 
useful information. Floating panel files are files that contain HTML and 
JavaScript, and that live in the Configuration/Floaters folder. 

4 Inspector — Inspectors are indispensable for defining, reviewing, and changing 
the name, size, appearance, and other attributes of the selection, as well as for 
launching internal and external editors for the selected element. Dreamweaver 
has several built-in interfaces for the Property inspector that let you set 
properties for many standard HTML tags. With custom property inspector 
files, you can override these built-in interfaces or create new ones to inspect 
custom tags. 

5 Behavior — You can add new behaviors to the Plus (+) menu in the Behaviors 
panel. A behavior is a user event plus an action. You write the action. To 
create a behavior, you write behavior code, create a user interface in HTML 
to get input, create a handler to the event to which you want your behavior 
associated, determine if your behavior applies to a given document, and apply 
the behavior in the appropriate location. The Configuration/Behaviors/ Actions 
folder contains many examples of behaviors. 

8 Data Translator — A translator provides a visual representation of non-HTML 
code in the Design view of the Document window. It converts non-HTML 
code into HTML and locks the non-HTML code to prevent it from being 
parsed by Dreamweaver. You create translator extensions to represent non- 
HTML code in the Design view of the Document window. 
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Extension foklers 

By familiarizing yourself with trie folders under the Configuration folder, you can 
discover the API for the areas you'll be extending and find working examples of 
each extension type. 

Tip: The Configuration_ReadMe.htm file in the Configuration folder provides details on the 
contents of each subfolder. 

One folder that does not correspond to a particular extension type is the Shared 
folder. The Shared folder is the central repository for utility functions, classes, 
and images that are commonly used by all extensions. For example, files in the 
Share d/MM/scripts/CMN folder contain functions that search all children of 
a node for a specific tag, strip spaces from a string, and generate the correct 
JavaScript reference to an object given its name, among other useful tasks. 

Installing an extension 

Before you program your own extension, download and install a pre-existing 
extension from the Macromedia Exchange Web site (http://macromedia.com/ 
exchange/). Taking time to do so helps in a couple of ways. You can get a good 
idea of how many extensions programmers there are in the community. You may 
have need for a particular extension that has been created already, or that is close 
enough to review and revise for your own purposes. 

Once you find an extension you are interested in on the Dreamweaver Exchange 
site, installing an extension is easy. 

To install an extension, take the following steps: 

1 If you haven't already done so, install the Package Manager. You can download 
it from the Macromedia Exchange Web site (http://www.macromedia.com/ 
software/ downloads/). 

2 Log on to the Macromedia Exchange Web site (http://www.macromedia.com). 

3 From the Macromedia Exchange Web site, select an extension you'd like to add. 
Pick a simple extension, one that will not drastically alter your Dreamweaver 
development environment. Click the download link on the extension detail 
page to download the extension package. 

4 Save the extension package in the Downloaded Extensions folder of your 
installed Dreamweaver folder. 

5 From the Package Manager File menu, select "Install Extension" (Commands > 
Manage Extensions). 

The extension is automatically installed in Dreamweaver. 
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Some extensions need Dreamweaver to restart before you can access them. If you 
are running Dreamweaver when you install the extension, you may be prompted 
to quit and restart the application. 

Go to the Package Manager (Commands > Manage Extensions) in Dreamweaver 
to view basic information on the extension (for example, where to access it within 
Dreamweaver). 



rraici 

This documentation was written before the code in Dreamweaver was complete. 
Thus, there may be some discrepancies between the final implementation of the 
JavaScript API in Dreamweaver and how it is documented in this book. A list of 
known issues can be found in the Extensibility section of the Dreamweaver 
Support Center at http://www.macromedia.com/support/dreamweaver/ 
extend.html. 



Conventions used in this guide 

The following typographical conventions are used in this guide: 

• Code font indicates code fragments and API literals, including class names, 
method names, function names, type names, scripts, SQL statements, and 
HTML tag and attribute names. 

• Italic code font indicates replaceable items in code. 

• The continuation symbol (->) indicates that a long line of code has been 
broken across two or more lines. Due to margin limits in this book's format, 
what is otherwise a continuous line of code must be split. When you see this 
continuation symbol in this book, consider the subsequent line to be a part 
of the first. When copying the lines of code, type the lines as one line. 

The following naming conventions are used in this guide: 

• You — the developer responsible for writing extensions. 

• The user — the person using Dreamweaver. 

• The visitor — the person who views the Web page as created by the user. 
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The Document Object Mode 
and JavaScript 



HTML documents consist of a tree of tags that reveals the document s structure. 
The root of the tree is the HTML tag. The two largest branches of the tree are HEAD 
and BODY. Offshoots of HEAD include TITLE, STYLE, SCRIPT, ISINDEX, BASE, 
META, and LINK. Offshoots of BODY include headings (HI, H2, and so on), block- 
level elements (P, DIV, FORM, and so on), text-level elements (FONT, BR, I MG, and so 
on), and the ADDRESS element. Leaves on the offshoots include attributes such as 
WIDTH, HEIGHT, ALT, and HREF. 

A document object model, or DOM, is also a tree that discloses the documents 
structure. The DOM, however, reports this structure in terms of objects and 
properties, rather than in terms of tags and attributes. 

The root of the DOM tree is the document itself, the HTML object is the trunk, 
and the rest of the objects in the document branch from the HTML object as the 
HTML tags and attributes do. 
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The document object model in 
Dreamweaver 



A browser's DOM determines how the JavaScript in an HTML document works 
in that browser. Similarly, Dreamweaver DOM determines how the JavaScript in 
extensions works in Dreamweaver. 

Dreamweaver DOM combines a subset of the Netscape Navigator 4.0 DOM with 
a subset of the World Wide Web Consortium (W3C) DOM Level 1. With the 
incorporation of DOM Level 1, every part of an HTML page has become an 
object — including tags (which the W3C calls elements), comments, and text. 

The basic breakdown of the DOM hierarchy is as follows: 



- navigator* 1 platform* — HTML tags 

-innerWidth* — forms 

-innerHeight* —images 

-screenX* —layers 

-screenY* — body* 

-document* _URL* 

— parentWindow* 

* denotes read-only I— child objects 

by name* 



Objects can be referred to by index (document . forms [3] . el ements[l]) or 
by name (document . my Form . myButton). Objects with the same name are 
collapsed into an array. You can access a particular object in the group by index 
(for example, the first radio button with the name my Radi oGroup in my Form 
would be referenced as document . my Form . my Radi oGroup[0]). 



The following table gives an overview of the properties, methods, and events 
supported by each object; these are described in more detail in books such as 
JavaScript: The Definitive Guide (O'Reilly). Additional details about the W3C 
properties and methods, which are less thoroughly documented by third parties, 
follow the table. A bullet (•) marks read-only properties. 



Object 



Properties 



Methods 



Events 



wi ndow 



navi gator 
document 



document • 
navigator • 
innerWidth • 
i nnerHei ght 
screenX • 
screenY • 



pi atform* 

forms • (an array of 
form objects) 
Images .(an array of 
image objects) 
layers .(an array of 
LAYER, I LAYER, and 
absolutely positioned 
DIVand SPAN objects) 
child objects by 
name • 
nodeType • 
parentNode • 
childNodes • 
documentEl ement 



alert( ) 
conf i rm( ) 
escape( ) 
unescape( ) 
cl ose( ) 
setTimeout( ) 
cl earT1meout( ) 
setlnterval ( ) 
cl earlnterval ( ) 
resi zeTo( ) 

None 

get El ementsBy 
TagName( ) 
hasChi 1 dNodes( ) 



onResi ze 



None 



onLoad 



all tags/elements 



body • 
URL . 

parentWindow • 

nodeType • 
parentNode • 
childNodes • 
tagName • 

attributes by 
name 

i nnerHTML 
outerHTML 



getAttri bute( ) 
setAttri bute( ) 
removeAttri bute 
() 

get El ementsByTa 
gName( ) 

hasChi 1 dNodesC ) 
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Object 



Properties 



Methods 



Events 



form In addition to the Only those methods None 

properties available for available to all tags, 
all tags: 

elements -(an array 
of button, checkbox, 
password, radio, reset, 
select, submit, text, file, 
hidden, image, and 
textarea objects) 
mmcol orbutton 
child objects by 
name • 



layer In addition to the Only those methods None 

properties available for available to all tags, 
all tags: 
vi si bi 1 i ty 
left 
top 
wi dth 
height 
zlndex 



image In addition to the Only those methods onMouseOver 

properties available for available to all tags. onMouseOut 
all tags: 

src 



submi t 



onMouseDown 
onMouseUp 



button In addition to the In addition to the onClick 

reset properties available for methods available for 

all tags: all tags: 

form • blurO 
focus( ) 



checkbox In addition to the In addition to the onClick 

ra (j -j o properties available for methods available for 

all tags: all tags: 

checked blurO 

form • focusO 

password In addition to the In addition to the onBlur 

text properties available for methods available for onFocus 

f1]e all tags: all tags: 

hidden form * blur() 

image(field) value focus() 

textarea select() 



Object 



Properties 



Methods 



Events 



sel ect 



In addition to the In addition to the on Bl ur (Windows 

properties available for methods available for only) 



opti on 



mmcol orbutton 



a may 
bool ean 
date 

functi on 

math 

number 

object 

st ri ng 

regexp 

text 



comment 



NodeLi st 
NamedNodeMap 



all tags: 
form • 

options • (an array 
of option objects) 

sel ectedlndex 



all tags: 
bl ur( ) (Windows 
only) 

focus ( ) (Windows 
only) 



onChange 



In addition to the Only those methods 
properties available for available to all tags, 
all tags: 

text 

In addition to the None 
properties available for 
all tags: 

name 
val ue 



Matches Netscape 4 Matches Netscape 4 None 



onChange 

on Focus (Windows 

only) 



None 



nodeType • 
parentNode 
chi 1 dNodes 
data 

nodeType • 
parentNode 
chi 1 dNodes 
data 

length • 
length • 



hasChi 1 dNodesQ None 



hasChildNodesQ None 



itemO None 
itemO None 
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The dreamweaver object and its properties 



Dreamweaver implements the standard objects as defined by the browsers and the 
W3C, as well as two custom objects: dreamweaver and si te. The dreamweaver 
object has two read-only properties associated with it: a pp Name and appVersion. 

appName has the value "Dreamweaver" or "Dreamweaver Ul tradev" for each 
respective application. appVersi on has a value of the form " versi onNumber 
[ 1 anguageCode] ( platform) ". For example, the value of the appVersi on 
property for the Swedish Windows version of Dreamweaver 4 would be "4.0 
[ s e ] (Win32)"; the value for the English Macintosh version would be "4.0 
[en] (MacPPC)". 

The appName and appVersi on properties were implemented in Dreamweaver 3 
and are not available in earlier versions of Dreamweaver. To determine whether 
the version of Dreamweaver is 3 or later, you can simply check for the existence 
of the appVersi on or appName property. To check for a specific version of 
Dreamweaver, check first for the existence of appVersi on and then for the 
version number. For example: 

if (dreamweaver . appVersi on && 
dreamweaver . appVersi on . i ndex0f( ' 3 . 01' ) != -1){ 
// execute code 

} 

The si te object has no properties. For more information about the methods of 
the dreamweaver and si te objects, see "The Dreamweaver JavaScript API" on 
page 205. 

DOM details 

Unlike the Netscape DOM, DOM Level 1 has not been documented in hundreds 
of third-party books and Web sites. Thus, this document will describe the DOM 
Level 1 properties and methods, and the values they return, in some detail. 

DOM Level 1 introduces four constants that describe the types of objects that 
make up the document tree (called nodes). These constants, which usually show 
up as return values for the nodeType property, are: 

Node . D0CUMENT_N0DE 
Node . ELEMENT_N0DE 
Node . C0MMENT_N0DE 
Node . TEXT_N0DE 



Properties and methods of the document object 



The following table lists the new properties and methods of the document object 
in Dreamweaver, along with their return values (with explanations, where 
appropriate). A bullet (•) marks read-only properties. 



Property or method 



Return value and explanation 



nodeType . 
parentNode • 
pa rentWi ndow 



chi 1 dNodes 



documentEl ement 



body 



URL 



get El ementsByTagName( tagName) 



Node . D0CUMENT_N0DE 



n u I 



The JavaScript object corresponding to the 
document's parent window. (This property is 
not included in DOM Level 1; however, it is 
supported by Microsoft Internet Explorer (IE) 
4.0.) 

A NodeLi st containing all the immediate 
children of the document object. Typically the 
document will have a single child: the HTM L 
object. 

The JavaScript object corresponding to the 
HTM L tag. This property is shorthand for getting 
the value of document .chi 1 dNodes and 
extracting the HTML tag from the NodeLi st. 

The JavaScript object corresponding to the 
BODY tag. This property is shorthand for calling 
document . documentEl ement . chi 1 dNode 
s and extracting the BODY tag from the 
NodeLi st. For frameset documents, this 
property returns the node for the outermost 
frameset instead. 

The file:// URL for the document or, if the file 
has not been saved, an empty string. 

A NodeLi stthat can be used to step through 
tags of type tagName (for example, I MG, D I V, 
and so on). 

If the tag argument is LAYER, the function 
returns all LA Y E R and I LA Y E R tags and all 
absolutely positioned DI V and SPAN tags. 
If the tagargument is INPUT, the function 
returns all form elements. (For this shortcut to 
work properly, all form field names must begin 
with a letter.) 



hasChildNodes( ) 



true 
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Properties and methods of HTML tag objects 



Every HTML tag is represented by a JavaScript object. Tags are organized in a tree 
hierarchy, where tag x is a parent of tag y if y falls completely within x's opening 
and closing tags (<x>x content surrounding <y>y content</y></x>). The 
following table lists the properties and methods of tag objects in Dreamweaver, 
along with their return values (with explanations, where appropriate). A bullet (•) 
marks read-only properties. 



Property or method 



Return value and explanation 



nodeType • 
pa rentNode 

chi 1 dNodes 

tagName • 

attrName 



i nnerHTML 



outerHTML 



Node . ELEMENT_NODE 

The parent tag. If this is the HTM L tag, then 
the document object is returned instead. 

A NodeLi st containing all the immediate 
children of the tag. 

The HTML name for the tag, such as I MG, 
A, or B L I N K. This value is always returned in 
uppercase letters. 

A string containing the value of the 
specified tag attribute, tag . attrName 
cannot be used if a 1 1 rName is a reserved 
word in the JavaScript language (for 
example, c 1 a s s). In this case, use 
getAttri buteC ) and setAttri bute( ) 
instead. 

The HTML source code contained 
between the begin tag and the end tag. For 
example, in the code<p><b>Hel 1 o</b> , 
Worl d ! </p>, p . i nnerHTML would return 
<b>Hel 1 o</b> , Worl d ! . If you write to 
this property, the DOM tree is immediately 
updated to reflect the new structure of the 
document. (This property is not included in 
DOM Level 1; however, it is supported by IE 
4.0.) 

The HTML source code for this tag, 
including the tag itself. For the example 
code above, p . outerHTML would return 
<p><b>Hello</b>, Worl d ! </p>. If you 
write to this property, the DOM tree is 
immediately updated to reflect the new 
structure of the document. (This property is 
not included in DOM Level 1; however, it is 
supported by IE 4.0.) 



getAttri bute( a tt rName) 



The value of the specified attribute if it is 
explicitly specified; otherwise, null. 



Property or method 



Return value and explanation 



getTransl a ted Attn" bute( attrName) 



The translated value of the specified 
attribute, or the same value that would be 
returned by get Attn bute( ) if the 
attribute's value is not translated. (This 
property is not included in DOM Level 1; it 
was added to Dreamweaver 3 to support 
attribute translation,) 



set Attn' bute( attrName, 
attrValue) 



removeAttri bute( attrName) 



get El ementsByTagName( tagName) 



hasChi 1 dNodesC ) 



hasTransl a ted Attn' butes( ) 



No return value. Sets the specified attribute 
to the specified value: for example, 
img . set Attn' bute( "src" , "image/ 
roses . gi f " ). 

No return value. Removes the specified 
attribute and its value from the HTML for 
this tag. 

ANodeList that can be used to step 
through child tags of type tagName (for 
example, IMG, D IV, and so on). 
If the tag argument is LAYER, the function 
returns all LAY E R and I LAY E R tags and all 
absolutely positioned DIVand SPAN tags. 
If the tag argument is I N PUT, the function 
returns all form elements. (For this shortcut 
to work properly, all form field names must 
begin with a letter.) 

A Boolean value indicating whether the tag 
has any children. 

A Boolean value indicating whether the tag 
has any translated attributes. (This property 
is not included in DOM Level 1; it was 
added to Dreamweaver 3 to support 
attribute translation.) 
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Properties and methods of text objects 



Each contiguous block of text in an HTML document (for example, the text 
within a P tag) is represented by a JavaScript object. Text objects never have 
children. The following table lists the properties and methods of text objects in 
Dreamweaver, along with explanations where appropriate. A bullet (•) marks 
read-only properties. 



Property or method 




Return value and explanation 


nodeType . 




Node . TEXT_N0DE 


parentNode • 




The parent tag. 


childNodes • 




An empty NodeLi st. 


data 




The actual text string . Entities in the text are 
represented as asingle character (for example, the 
text Joseph & I is returned as Joseph & I). 


hasChi 1 dNodes( ) 




fal se 


Properties and methods < 


)f comment objects 


Each HTML comment is represented by a JavaScript object. The following table 
lists the properties and methods of comment objects in Dreamweaver, along with 
explanations where appropriate. A bullet (•) marks read-only properties. 


Property or method 




Return value and explanation 


nodeType • 




Node . C0MMENT_N0DE 


parentNode • 




The parent tag. 


childNodes • 




An empty NodeLi st. 


data 




The text string between the comment markers 

(<! -- and -->). 


hasChildNodesO 




fal se 



How JavaScript works in extensions 



When Dreamweaver processes extensions, it compiles everything between SCR I PT 
tags and executes any code within SCR I PT tags that is not part of a function 
declaration (for example, initialization of global variables). It also reads in, 
compiles, and executes scripts in external JavaScript files specified in the SRC 
attributes of SCR I PT tags. 

Note: If any JavaScript code in your extension files contains the string ' </ SCRIPT) ' , 
the JavaScript interpreter reads this as an actual closing SC R I PT tag and reports an 
unterminated string literal error. To avoid this problem, break the string into pieces and 
concatenate them, like this: '< ' + '/SCRIPT)'. 

In command and behavior action files, Dreamweaver executes code in the 
on Load event handler (if one appears in the BODY tag) when the user chooses the 
command or action from a menu. In object files, Dreamweaver executes code in 
the on Load event handler on the BODY tag if the body of the document contains a 
form. Dreamweaver ignores the on Load handler on the BODY tag in data translator, 
Property inspector, and floating panel files. In all extensions, Dreamweaver 
executes code in other event handlers (for example, on Bl u r=" a 1 e rt ( ' Th i s is 
a requi red field.')") when the user interacts with the form fields to which 
they are attached. 

Links (a tags, including those with JavaScript URLs such as 
<a href=" javascri pt : a 1 ert( ' hi ' ) ">), are not supported, nor is the 
document . wri te( ) statement. Plug-ins (set to pi ay at all times) are supported 
in the BODY of extensions, but Java applets and ActiveX controls are not. 

Running scripts at startup or shutdown 

In Dreamweaver 4, if you place a command file in the Configuration/Startup 
folder, the command runs as Dreamweaver is starting up. Startup commands load 
before the menus.xml file, before the files in the ThirdPartyTags folder, and before 
any other commands, objects, behaviors, inspectors, floating panels, or translators. 
Thus, you can use startup commands to modify the menus.xml file or other 
extension files. You can also show warnings, prompt the user for information or 
call dreamweaver . runCommand ( ), but you cannot call a command that expects a 
valid DOM. 

Similarly, if you place a command file in the Configuration/Shutdown folder, 
the command will run as Dreamweaver is shutting down. You can call the 
dreamweaver . runCommand ( )from shutdown commands, show warnings, or 
prompt the user for information, but you cannot stop the shutdown process. 

For more information about commands, see "Commands" on page 37. 
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Custom JavaScript controls 



Dreamweaver's Extensibility architecture provides support for the basic HTML 
form elements such as sel ect and input, which can be further utilized in 
extensions to add new controls to the Dreamweaver UI. Two examples of this 
extended support are the built-in tree control and color button control. 

Tree controls 

The tree control displays data in a hierarchical format and allows users to expand 
and collapse views of the data. The data is stored in the tree in a collection of 
"data nodes." Data nodes may contain other data nodes, referred to as "child 
nodes." Nodes at the extreme reaches of the tree are referred to as "leaf nodes." 
Leaf nodes, by definition, contain no child nodes of their own. The first node in 
the tree is referred to as the "root" node. 

In Dreamweaver, the Keyboard Shortcuts editor uses the tree control: 



Keyboard Shortcuts 



SvW, ' ) Macromedia Standard ^3 



if: audi ; Menu Commands 



Undo 

• Redo 
Cut 
Copy 
Paste 
Clear 

• Select All 

• Select Parent Tag.. 



CtrkZ^lt+BkSp 
Ctrl+YXtrl+Shift+Z || 
CtrkXShift+Del || 
Ctrl+C,Ctrl+lns 
Ctrl+V.Shift+lns ||£ 

II 

Ctrl+Shift+< M§ 



1111 >j ij 



r..Y....Y.....v.y.y^ 



Clicking on a node once selects it. In Windows, the node buttons are +/- buttons. 
On the Macintosh, the nodes are turn-down triangles. Nodes that contain child 
nodes are expandable and collapsible by clicking on the associated button next to 
the node. 
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Instantiating a tree control 

A tree control uses three new tags (Dreamweaver uses the MM : prefix to distinguish 
the tag from standard HTML): 

• MM : TREECONTROL indicates to Dreamweaver that the form element is a 
tree control. 

• MM : TREECOLUMN specifies a column in the tree control. 

• MM : TREENODE specifies one node in the tree control. 

MM:TREECONTROL The MM : TREECONTROL tag is a new HTML element that 
the user can specify in an extension document to instantiate a tree control. The tag 
has several attributes, properties, events, and methods. 

Although the MM : TREECONTROL tag is non-empty, it may not contain raw text. 
The only valid content for an MM : TREECONTROL tag is at least one or more 
MM: TREECOLUMN tags and zero or more MM: TREENODE tags. 

The HTML attributes for an MM : TREECONTROL tag are: 



Attribute Name 


Description 


Sample 


name 


Name of the tree control. 


< MM TREECONTROL 

name="MyTree"> 

</MM:TREECONTROL> 


size 


Number of rows to size the 
control for. (optional) Default is 5 
rows. 


<MM:TREECONTROLsize="6"> 
</MM:TREECONTROL> 


multiple 


Allows a tree to have multiple 
selections. Default is single- 
selection, (optional) 


<MM:TREECONTROL 
MULTIPLE> 

</MM:TREECONTROL> 


style 


Style definition for height and 
width of tree control. If specified, 
takes precedence over SIZE 
attribute, (optional) 


<MM:TREECONTROL 
style="width:100px;height:200px" 

> 

</MM:TREECONTROL> 


noheaders 


Indicates that the tree column 
headers won't be displayed if this 
attribute is present. 


<MM:TREECONTROL 
noheaders"> 

</MM:TREECONTROL> 



MM:TREECOLUMN The MM : TREECOLUMN tag specifies a column in the tree 
control. You must sepcify at least one MM: TREECOLUMN tag. 
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The syntax for an MM : TREECOLUMN tag is: 



Attribute Name 


Description 


Sample 


name 


Name of the column. 


<MM TREECOLUMN 
name="Column1"> 


value 


String to appear in column 
header. 


<MM:TREECOLUMN 
value="Files"> 


width 


Width of the column, in pixels. 
Percentage not supported. 
Default is 100. 


<MM:TREECOLUMN 
width="60"> 


align 


Alignment of column text - 'left', 
'right', or 'center'. Default is left. 


<MM TREECOLUMN 
align="center"> 


state 


State of the column- "visible" or 
"hidden". 


<MM:TREECOLUMN 
state="visible"> 



TREECOLUMN tags should appear at the top of the TreeControl declaration, such as: 

<MM : TREECONTROL name=" t reel " > 

<MM : TREECOLUMN name= M Col umnl " width="100" state= M vi si bl e"> 
<MM : TREECOLUMN name= M Col umn2 " width="80" state=" vi si bl e"> 

</MM : TREECONTROL) 



Note: TREECOLUMN tags can technically appear anywhere in the TREECONTROL tag, but 
should be placed at the top for readability. 

MM:TREENODE The MM : TREENODE tag specifies an individual node within 
an MM : TREECONTROL. It is a non-empty tag and may contain only other 
MM: TREENODE tags. 

The MM : TREENODE tag may not contain raw text, even though it is non-empty. 
The only valid content for an M M : T R E E N 0 D E tag is zero or more MM : TREENODE tags. 



The MMiTREENODE attributes are: 



Attfihi it#^ N^mp 
Miiriuuit; iNctiiic 


Ucoui ipiiui l 


Odl I l|Jlc 


name 


m rii -ri — > i — i — M/-\ni — i 

Name of the TREENODE tag. 


J \ Ah A ~T~ 1 — 1 1 — 1 — M/-\r\l — 

<MM:TREENODE 






name="node1"> 






</MM TREE NOD E> 


value 


Contains the content for the 


<MM:TREENODE 




given node. For more than one 


value="Lawnmower|129.95"> 




column, this will be a pipe- 


</MMTREENODE> 




delimited string. To specify an 
empty column, place a single 


/ / civ a D"r\/ r*r~\\ CVAN/IDI c. 

// blvlr I Y LUL bXAIVlrLb. 




space character before the pipe. 


<MMTREENODE 
value="Data| |"> 






</IVIIVI. I rxIZIZI n^JUO 


state 


State of the node - "expanded" 


<MMTREENODE 




or "collapsed". 


state="expanded"> 






</MMTREENODE> 


selected 


True if the node is currently 


<MM:TREENODE selected> 




selected. You can select multiple 


</MM:TREENODE> 




nodes by setting this attribute on 




more than one tree node, if the 






tree has a MULTIPLE attribute. 




icon 


Integer index of built-in icon to 


<IVIM. I KLLIMUUL ICOn= I > 




use, starting with 0. The built-in 


</IVIIVI. I KLLINJUUL> 




icons are: 




0 = no icon 






1 = DW document icon 






2 = multi-document icon 






3 = folder 






4 = image document 






5 = green check 






6 = red X 






7= question mark 






8 = note icon 






9 = warning icon 






10 = stop icon 





A typical set of tree control code might look like: 

<MM : TREECONTROL name="Ctrl Name" [size=N] 

[styl e=" [width: #px] ; [height :#px]"]> 

<MM : TREECOLUMN name="Col umnl " val ue=" Items") 

<MM : TREENODE val ue=" Iteml " sel ectedX/MM : TREENODE) 

<MM : TREENODE val ue= H I tem2 | Item3" expanded) 

<MM: TREENODE val ue=" I tem4 | I tem5"X/MM : TREENODE) 

</MM : TREENODE) 

</MM : TREECONTROL) 
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Manipulating tree control content 



TREECONTROLS and TREENODES are implemented as HTML tags, and are thus 
parsed by Dreamweaver and stored in the document tree. These tags can then be 
manipulated just like any other document node by calling DOM functions and 
using DOM properties already built into Dreamweaver. 

Adding nodes Currently Dreamweaver does not have a DOM function 
for creating new nodes within the document structure. Dreamweaver does 
support two properties, i nnerHTML and outerHTML, that can be used to 
simulate this function. 

For example, to add a child node to an existing empty parent node, you would set: 

parentNode . i nnerHTML = "<MM : TREENODE name="X" val ue=' myNewNode 
expandedX/MM :TREEN0DE>" 

Deleting nodes Currently, Dreamweaver does not support a DOM function for 
deleting a node from the document structure. This behavior can be simulated 
using the i nnerHTML and outerHTML properties. 

For example, to delete all child nodes of a given parent node, you would set: 

parentNode . i nnerHTML = "" 

Moving nodes Dreamweaver does not currently provide a DOM function 
for moving one node to another location within the document. This action can 
be simulated using a combination of adding and deleting nodes (using the 
i nnerHTML and outerHTML properties). 

Modifying nodes Nodes can be directly modified using the provided 
Dreamweaver DOM functions. 

For example, to set the "expanded" attribute of a tree node, a scripter can simply 
use the DOM function NODE . setAttri bute( ' expanded ' , ' expanded ' ) to 
expand the node. All other attributes can be controlled the same way. 

Traversing nodes Dreamweaver does not have built in API functions for 
traversing, or iterating, through nodes. This behavior can be simulated using 
the parentNode, chi 1 dNodes, and hasChi 1 dNodes( ) properties and methods. 

For example, to retrieve the parent node of a node, you would use: 

parent = node . pa rentNode ; 

Getting node data Node data can be retrieved directly from the node using 
the provided Dreamweaver DOM node functions and properties such as 

get Attn bute( ), i nnerHTML, and outerHTML. 

For example, to see if a node was selected, you could use: 

bSelected = ( node . getAttri bute( ' sel ected ' ) != null) 



A Color Button Control for extensions 

A Color Button Control lets you add a color picker interface to your extensions. 
You instantiate a color button using the existing HTML form input tag with the 
type attribute of the control set to "mmcol orbutton", and then provide the name 
and value attributes accordingly. The name attribute is the name of the color 
button. The value attribute is the current color value, represented as either a 
hexadecimal string or as a color name. 

Here are some examples of the mm col orbutton tag: 

<input type="mmcol orbutton" name="col orbutton " val ue="#FF0000"> 
<input type="mmcol orbutton" name="col orbutton " val ue=" teal "> 

A color button has one event, on Change, which is triggered when the color 
is changed. 



The Document Object Model and JavaScript 29 



30 Chapter 2 




CHAPTER 3 

Objects 



Objects are designed to insert a specific string of code into the users document. 
An object appears in a category on the Objects panel and in the Insert menu once 
its Object file is stored in a subfolder within the Configuration/ Objects folder 
inside the Dreamweaver application folder. 

Objects have two components: the Object file that defines what is inserted 
in your document; and the 18 by 18 pixel GIF image that appears in the 
Objects panel. 

Objects are HTML files. The BODY of an Object file can contain an HTML form 
that accepts parameters for the object (for example, the number of rows and 
columns in the table to be inserted). The HEAD of an Object file contains 
JavaScript functions that process form input from the BODY and control what 
is added to the users document. 

Note: The simplest objects contain only the HTML to be inserted, with no BODY and HEAD 
tag. See "Customizing Dreamweaver" in Using Dreamweaver for more information. 
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How object files work 



When a user selects an object by clicking an icon in the Objects panel or by 
choosing an item in the Insert menu, the following chain of events occurs: 



FORM does not exist 




: wmctowBiniensionsO 



windowDimensionsO 
■ defined, otherwise 
" Dreamweaver auto- 
sizes dialog box 



user enters parameters 
defined in the FORM 




Object Process diagram 



1 The Object file is scanned for a FO RM tag. If a form exists — and if the 
Show Dialog When Inserting Objects option is selected in the General 
preferences — Dreamweaver calls the wi ndowDi mensi ons ( ) function, if 
defined, to determine the size of the dialog box in which to display the form. 
If no form exists in the Object file, Dreamweaver does not display a dialog 
box, and step 2 is skipped. 

2 If Dreamweaver displayed a dialog box in step 1, the user enters parameters for 
the object (such as the number of rows and columns in a table) in the dialog 
box and clicks OK. 

3 The objectTagO function is called, and its return value is inserted into the 
document after the current selection (it does not replace the current selection). 
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The object API 

The custom functions in the object API are not required. The functions in the 
object API differ from the functions in the main JavaScript API in three ways: 

• They are not methods of the dreamweaver, dom, or si te object. 

• They are significant only in the context of Object files. That is, Dreamweaver 
automatically calls the objectTagO function if it is defined in an Object file, 
whereas a function named objectTag( ) acts like a user-defined function in 
any other extension file — you have to call it explicitly. 

• You are responsible for writing the body of each function and returning a value, 
if required. This is the opposite of how the functions work in the main API: 
those you call and pass arguments to, and Dreamweaver generates return 
values, if any. Here Dreamweaver calls the functions and passes arguments to 
them, and you generate return values, if any. 

dispIayHelpQ 

Description 

If this function is defined, displays a Help button below the OK and Cancel 
buttons in the Parameters dialog box. This function is called when the user clicks 
the Help button. 

Arguments 

None. 

Returns 

Nothing. 

Example 

The following instance ofdisplayHelpO opens in a browser window a file with 
instructions for using the object: 

functi on di spl ayHel p( ) { 

dreamweaver . browse Documents ' http : //peopl e . netscape . com/ 
andreww/dreamweaver^ 

/objects . html ' ) ; 

} 
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isDomRequiredQ 



Description 

Determines whether the object requires a valid DOM to operate. If this function 
returns true or if the function is not defined, Dreamweaver assumes that the 
command requires a valid DOM and synchronizes the Code and Design views for 
the document before executing. Synchronization causes all edits in the Code view 
to be updated in the Design view. 

Arguments 

None. 

Returns 

true if a command requires a valid DOM to operate, f a 1 se if not. 



objeetTagQ 

Description 

Inserts a string of code into the users document. 

Arguments 

None. 

Returns 

The string to be inserted. 
Example 

The following instance ofobjectTagO inserts an OBJECT/EMBED combination 
for a specific ActiveX control and plug-in: 

functi on objectTag( ) { 
return '\n' + 

'<0BJECT CLASSID= M cl si d : 1 66F1 00 B - 3A9R - 1 1 FB - 807 5444 553540000 " \n' + 

' C0DEBASE=" http : //www. my si te.com/product/cabs/^ 

myproduct.cab#version=l ,0,0,0" \n' + 

' NAME="MyProductName"> \n' + 

' <PARAM NAME=" SRC " VALUE=""> \n' + 

' < EMB ED SRC="" HE I GHT=" " WIDTH=" " NAME="MyProductName"> \n' + 

'</0BJECT>' 

} 
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wmdowDsmenssons{) 



Description 

Sets specific dimensions for the Parameters dialog box. If this function is not 
defined, the window dimensions are computed automatically. 

Note: Do not define this function unless you want an Options dialog box larger than 
640x480 pixels. 

Arguments 

pi atform 

The value of the argument is either "maci ntosh " or " wi ndows ", depending on 
the users platform. 

Returns 

A string of the form "wi dth In Pixel s , hei ght In Pixel s". 

The returned dimensions are smaller than the size of the entire dialog box because 
they do not include the area for the OK and Cancel buttons. If the returned 
dimensions do not accommodate all options, scroll bars appear. 

Example 

The following instance of wi ndowDi men si ons ( ) sets the dimensions of the 
Parameters dialog box to 648 x 520 pixels if the platform is Windows, and 
660 x 580 pixels if the platform is Macintosh: 

functi on wi ndowDimensi ons (pi atform) { 
var retval = 

if (platform = = "windows")! 
retval = "648, 520"; 
}el se{ 

retval = "660, 580"; 
} 

return retval ; 

} 
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Adding objects to the Objects panel 



Dreamweaver automatically adds any files that are inside one of the subfolders in 
the Configuration/Objects folder to the category associated with the subfolder. 
For example, a file inside the Configuration/ Objects/MyObjects folder would 
appear on the MyObjects category of the Objects panel. 

Note: Although Object files can be stored in separate folders, it's important that their file 
names be unique. The dom.insertObject() function, for example, looks for a specified file 
anywhere within the Objects folder without regard to subfolders. If a file called Button.htm 
exists in the Forms folder and also in the MyObjects folder, Dreamweaver cannot 
distinguish between them. 

Each Object file has an associated 18x18 pixel GIF image that appears in the 
Objects panel. The Image file must have the same base name as the Object file 
(for example, object.gif is associated with object.htm) to ensure that the files 
remain connected. 

If you create a larger object image, Dreamweaver will scale it to 18x18 pixels. If 
you do not create an image for your object, a default object icon appears in the 
Objects panel. 



Adding objects to the Insert menu 

Dreamweaver automatically adds to the bottom of the Insert menu any files that 
are inside one of the subfolders in the Configuration/ Objects folder. 

To control the position of an object in the Insert menu or any other menu, or to 
add an object to multiple menus, you can modify the menus.xml file. This file 
controls the entire menu structure for Dreamweaver. For more information 
about modifying the menus.xml file, see "Customizing Dreamweaver" in 
Using Dreamweaver. 

Note: In Dreamweaver 2 and earlier, the items in the Insert menu were controlled by a file 
called lnsertMenu.htm. This file has been superseded by menus.xml. 
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CHAPTER 4 

Commands 



Commands can be used to perform almost any kind of edit to the users 
current document, other open documents, or to any HTML document on 
a local drive. Commands can insert, remove, or rearrange HTML tags and 
attributes, comments, and text. 

Commands are HTML files. The BODY of a Command file can contain an HTML 
form that accepts options for the command (for example, how a table should be 
sorted and by which column). The HEAD of a Command file contains JavaScript 
functions that process form input from the BODY and control what edits are made 
to the user's document. 
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How commands work 

When a user clicks a menu that contains a command, the following chain of 
events occurs: 



Begin 

User selects the command 
or the command is run ™f* 
via the dw.runCommandO 
function 



Dreamweaver displays 
any buttons defined in 
the commandButtons() 
function 



11 

If a form exists, 
Dreamweaver creates 
a dialog box of 
command options 



Command process and dialog box integration diagram 



1 Dreamweaver calls thecanAcceptCommandO function, if defined, in each 
Command file referenced in the menu to see whether this command is 
appropriate for the selection. If canAcceptCommand ( ) returns fal se, the 
command is dimmed in the menu. 

2 The user chooses a command from the menu. 

3 Dreamweaver calls the receiveArgumentsO function, if defined, in the 
selected Command file to give the command an opportunity to process any 
arguments passed from the dreamweaver . runCommand ( ) function. 
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receiveArgumentsO 
;~; processes arguments, 
if defined, from the 
dw.runCommandO function 



NOTE: If an option dialog box 
was defined or necessary, it will 
remain visibleuntil ascript in the 
selected command calls 
window.closeO 




User selects 
command options 
from the dialog box, 
if defined in the form 



4 Dreamweaver calls the comma nd Button s ( ) function, if defined, to determine 
which buttons appear along the right side of the Options dialog box and what 
code should be executed when the user clicks the buttons. 

5 Dreamweaver scans the Command file for a FORM tag. If a form exists, 
Dreamweaver calls the wi ndowDi men si ons ( ) function to determine the 
size of the Options dialog box containing the BODY elements of the file. If 

wi ndowDi mens i ons ( ) is not defined, the size of the dialog box is determined 
automatically. 

8 If the Command files BODY tag contains an on Load handler, Dreamweaver 
executes it (whether or not a dialog box is displayed). If no dialog box appears, 
the remaining steps do not occur. 

7 The user selects options for the command. Dreamweaver executes event 
handlers associated with the fields as the user encounters them. 

8 The user clicks one of the buttons defined by comma nd Button s ( ) . 

9 Dreamweaver executes the code associated with the button that was clicked. 

10 The dialog box remains visible until one of the scripts in the command calls 

wi ndow.cl ose( ). 

The command API 

The custom functions in the command API are not required. The functions in the 
command API differ from the functions in the main JavaScript API in three ways: 

• They are not methods of the dreamweaver, dom, or si te object. 

• They are significant only in the context of Command files. That is, 
Dreamweaver automatically calls thecommandButtonsO function if it is 
defined in a Command or Menu Command file, whereas a function named 
comma nd Button s ( ) acts like a user-defined function in any other extension 
file — you have to call it explicitly. 

• You are responsible for writing the body of each function and returning a value, 
if required. This is the opposite of how the functions work in the main API: 
those you call and pass arguments to, and Dreamweaver generates return 
values, if any. Here Dreamweaver calls the functions and passes arguments to 
them, and you generate return values, if any. 



Commands 
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canAcceptCommandQ 



Description 

Determines whether the command is appropriate for the current selection. 

Note: Do not define canAcceptCommand ( ) unless it returns f al se in at least one case. If 
the function is not defined, the command is assumed to be appropriate; making this 
assumption saves time and improves performance. 

Arguments 

None. 

Returns 

true if the command is allowed; fa 1 se if it is not, dimming the command 
in the menu. 

Example 

The following instance of canAcceptCommand ( ) makes the command available 
only when the selection is a table: 

function canAcceptCommand () { 

var sel Ob j=dw. get Document DOM . get Sel ec ted Node ( ) ; 
return ( sel Obj . nodeType == Node . ELEMENT_NODE && - 
selObj.tagName=="TABLE M ); 

} 

commandButtonsQ 

Description 

Defines the buttons that should appear on the right side of the Options dialog 
box and their behavior when clicked. If this function is not defined, no buttons 
appear, and the BODY of the Command file expands to fill the entire dialog box. 

Arguments 

None. 

Returns 

An array containing an even number of elements. The first element is a string 
containing the label for the topmost button. The second element is a string of 
JavaScript code that defines the behavior of the topmost button when clicked. 
Remaining elements define additional buttons in the same manner. 

Example 

The following instance ofcommandButtonsO defines three buttons: OK, Cancel, 
and Help. 

function commandButtons ( ) { 

return new ArrayC'OK" , "doCommand ( ) " , -< 

"Cancel" , "wi ndow . cl ose( ) " , "Help" , "showHel p( ) " ) ; 

} 
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isDomRequiredQ 



Description 

Determines whether the command requires a valid DOM to operate. If this 
function returns t rue or if the function is not defined, Dreamweaver assumes that 
the command requires a valid DOM and synchronizes the Design and Code views 
of the document before executing. Synchronization causes all edits in the code 
view to be updated in the Design view. 

Arguments 

None. 

Returns 

true if a command requires a valid DOM to operate, f a 1 se if not. 

recesveArguments{) 

Description 

Processes any arguments passed from a menu item or from dw . run Command ( ), if 
any arguments were given to the dw . runCommand ( ) function. 

Arguments 

{arglj, {arg2} y ...(argN} 

If the a rgu merits attribute is defined foramenuitem tag, the value of that 
attribute is passed to the recei veArguments ( ) function as one or more 
arguments. The a rguments attribute is useful for distinguishing between two 
menu items that call the same menu command. Arguments can also be passed 
to a command by the dw. runCommand ( ) function. 

Returns 

Nothing. 
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wmciowDsmenssonsO 

Description 

Sets specific dimensions for the Parameters dialog box. If this function is not 
defined, the window dimensions are computed automatically. 

Note: Do not define this function unless you want an options dialog box larger than 
640x480 pixels. 

Arguments 

pi atform 

The value of the argument is either "maci ntosh " or " wi ndows depending on 
the users platform. 

Returns 

A string of the form "wi dth In Pixel s , hei ght In Pixel s". 

The returned dimensions are smaller than the size of the entire dialog box 
because they do not include the area for the OK and Cancel buttons. If the 
returned dimensions do not accommodate all options, scroll bars appear. 

Example 

The following instance of wi ndowDi men si ons ( ) sets the dimensions of the 
Parameters dialog box to 648 x 520 pixels: 

function wi ndowDi mensi ons ( ) { 
return "648,520"; 

} 

sample command example 

The following command converts the selected text to all lowercase 
characters. The command is very simple; it does not display a dialog box, 
so the commandButtons( ) function is not defined. 

<HTML> 
<HEAD> 

<TITLE>Make Lower Case</TITLE> 
<SCRIPT LANGUAGE=" Java script") 

function canAcceptCommand ( ) { 

// Get the DOM of the current document 

var theDOM = dw . getDocumentDOM( ) ; 

// Get the offsets of the selection 

var theSel = theDOM . getSel ecti on () ; 

// Get the selected node 

var theSelNode = theDOM . getSel ectedNode( ) ; 

// Get the children of the selected node 

var theChildren = theSel Node . chi 1 dNodes ; 
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// If the selection is not an insertion point, and 

// either the selection or its first child is a 

// text node, return true, 
return (theSel [0] != theSel [1] && ( theSel Node . nodeType == - 
Node . TEXT_N0DE || theChi 1 dren [0] . nodeType == Node . TEXT_N0DE ) ) ; 



function changeToLowerCase( ) { 
// Get the DOM again 
var theDOM = dw . getDocumentDOM( ) ; 
// Get the offsets of the selection 
var theSel = theDOM . getSel ecti on () ; 

// Get the outerHTML of the HTML tag (the 
// entire contents of the document) 
var theDocEl = theDOM . documentEl ement ; 
var theWholeDoc = theDocEl . outerHTML ; 

// Extract the selection 

var selText = theWhol eDoc . substri ng( theSel [0] , theSel [1 ]) ; 

// Re-insert the modified selection into the document 
theDocEl .outerHTML = theWhol eDoc . substri ng( 0 , theSel [0] ) + -■ 
sel Text . toLowerCase( ) + theWhol eDoc . substri ng( theSel [1 ]) ; 

// Set the selection back to where it was when you 
// started 

theDOM. setSel ecti on (theSel [0] , theSel [1]); 



</SCRIPT> 
</HEAD> 

< BODY onLoad="changeToLowerCase( ) "> 

• <!-- The function that does all the work in this command is -i 

• called from the onLoad handler on the BODY tag. There is no -i 

• form in the BODY, so no dialog box appears. — > 

</B0DY> 
</HTML> 
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Aoosny coninianas lo ino L^oronianos rn©nu 



Dreamweaver automatically adds to the bottom of the Commands menu any files 
that are inside the Configuration/Commands folder. To prevent a command from 
appearing in the Commands menu, put the following comment on the first line of 
the file: 

<!-- MENU- L0CATI0N=N0NE --> 

In Dreamweaver 1 and 2, if you wanted to control the position or text associated 
with a command, you could add it explicitly to the CommandMenu.htm file. In 
Dreamweaver 3, this file was superseded by the menus .xml file, which controls the 
entire menu structure for Dreamweaver. For more information about modifying 
the menus.xml file, see "Customizing Dreamweaver" in Using Dreamweaver. 
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Dreamweaver 3 introduced a new type of command that made menus more 
flexible and dynamic menus possible. Like regular commands, menu commands 
can be used to perform almost any kind of edit to the current document, other 
open documents, or any HTML document on a local drive. The menu commands 
API expands the regular command API to accomplish several tasks related to 
displaying and calling the command from the menu system. 

Note: Because menu commands are directly related to the menu system in Dreamweaver, 
you should read "Customizing Dreamweaver," in Using Dreamweaver before continuing. 

Menu commands are HTML files. The BODY of a Menu Command file can 
contain an HTML form that accepts options for the command (for example, 
how a table should be sorted and by which column). The HEAD of a Menu 
Command file contains JavaScript functions that process form input from 
the BODY and control what edits are made to the user's document. 

Menu commands are stored in the Configuration/Menus folder inside the 
Dreamweaver application folder. 

Note: If you are adding your own menu commands to Dreamweaver, add them at the top 
level of the Menus folder or create your own subfolder. The MM folder is reserved for the 
menu commands that ship with Dreamweaver. 
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How menu commands work 



When the user clicks a menu that contains a menu command, the following chain 
of events occurs: 

1 If any menui tern tag in the menu contains the dynami c attribute, Dreamweaver 
calls thegetDynamicContentO function in the associated Menu Command 
file to populate the menu. 

2 Dreamweaver calls thecanAcceptCommandO function in each Menu 
Command file referenced in the menu to check whether the command is 
appropriate for the selection. If canAcceptCommand ( ) returns fal se, the 
menu item is dimmed. 

If canAcceptCommand ( ) returns true or is not defined, Dreamweaver calls the 
isCommandCheckedO function to determine whether to display a check mark 
next to the menu item. IfisCommandCheckedO is not defined, no check mark 
is displayed. 

3 Dreamweaver calls the setMenuText ( ) function to determine the text that 
should appear in the menu. If setMenuText ( ) is not defined, Dreamweaver 
uses the text that is specified in the menui tern tag. 

4 The user selects an item from the menu. 

5 Dreamweaver calls the receiveArgumentsO function, if defined, in the 
selected Menu Command file to let the command process any arguments 
passed from the menu item. 

6 Dreamweaver calls the comma nd Button s ( ) function, if defined, to determine 
which buttons appear along the right side of the Options dialog box and what 
code should be executed when the user clicks the buttons. 

7 Dreamweaver scans the Menu Command file for a FO RM tag. If a form 
exists, Dreamweaver calls the wi ndowDi men si ons ( ) function to determine 
the size of the Options dialog box containing the BODY elements of the file. If 
wi ndowDi men si ons ( ) is not defined, the size of the dialog box is determined 
automatically. 

8 If the Menu Command file's BODY tag contains an on Load handler, 
Dreamweaver executes the code associated with the handler (whether or 
not a dialog box is displayed). If no dialog box appears, the remaining steps 
do not occur. 

9 The user selects options in the dialog box. Dreamweaver executes event 
handlers associated with the fields as the user encounters them. 

10 The user clicks one of the buttons defined bycommandButtonsO. 

11 Dreamweaver executes the code associated with the clicked button. 

12 The dialog box remains visible until one of the scripts in the menu command 
calls wi ndow. cl ose( ). 
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The menu command AP 



The custom functions in the menu command API are not required. The functions 
in the menu command API differ from the functions in the main JavaScript API 
in three ways: 

• They are not methods of the d reamwea ver, dom, or site object. 

• They are significant only in the context of Menu Command files. That 
is, Dreamweaver automatically calls thegetDynamicContentO function 
if it is defined in a Menu Command file, whereas a function named 
getDynamicContentO acts like a user-defined function in any other 
extension file — you have to call it explicitly. 

• You are responsible for writing the body of each function and returning a value, 
if required. This is the opposite of how the functions work in the main API: 
those you call and pass arguments to, and Dreamweaver generates return 
values, if any. Here Dreamweaver calls the functions and passes arguments 

to them, and you generate return values, if any. 

canAccepiCommandQ 

Description 

Determines whether the menu item should be active or dimmed. 
Arguments 

(argil, (arg2},...{argNj } 

If the a rguments attribute is defined for a men ui tern tag, the value of that 
attribute is passed to the canAcceptCommand ( ) function (and to the 
i sCommandChecked( ), recei veArguments( ), and setMenuText( ) functions) 
as one or more arguments. The a rguments attribute is useful for distinguishing 
between two menu items that call the same menu command. 

Returns 

A Boolean value indicating whether the item should be enabled. 
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commandButtonsQ 



Description 

Defines the buttons that should appear on the right side of the Options dialog 
box and their behavior when clicked. If this function is not defined, no buttons 
appear, and the BODY of the Menu Command file expands to fill the entire 
dialog box. 

Arguments 

None. 

Returns 

An array containing an even number of elements. The first element is a string 
containing the label for the topmost button. The second element is a string of 
JavaScript code that defines the behavior of the topmost button when clicked. 
The remaining elements define additional buttons in the same manner. 

Example 

The following instance ofcommandButtonsO defines three buttons: OK, Cancel, 
and Help. 

function commandButtons ( ) { 

return new ArrayC'OK" , "doCommand ( ) " , "Cancel" , -> 
"window. cl ose( ) " , "Help" , " showHel p( ) " ) ; 

} 

getDynamgcContent() 

Description 

Retrieves the content for the dynamic portion of the menu. 

Arguments 

menuID 

The argument is the value of the i d attribute in the men ui tern tag associated with 
the item. 

Returns 

An array of strings. Each string contains the name of a menu item and its unique 
ID, separated by a semicolon. If the function returns null, then no change is 
made to the menu. 
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Example 

The following instance of get Dy nam i eContent () returns an array of four menu 
items (My Menu Item 1, My Menu Item 2, and so on): 

function getDynami eContent () { 
van stringArray= new ArrayO; 
var 1=0; 

van numltems = 4; 

for (1=0; KnumI terns ; 1++) 

stri ngArray[i ] = new StringCMy Menu Item " + i + ";id=" + 1); 

return strlngArray; 

} 

isCommandCheckedQ 

Description 

Determines whether to display a check mark next to the menu item. 
Arguments 

{argl}, {arg2},...{argN} 

If the a rguments attribute is defined foramenuitem tag, the value of that 
attribute is passed to the 1 sCommandChecked ( ) function (and to the 
canAcceptCommand( ), recei veArguments( ), and setMenuText( ) functions) 
as one or more arguments. The a rguments attribute is useful for distinguishing 
between two menu items that call the same menu command. 

Returns 

A Boolean value indicating whether a check mark should appear next to the 
menu item. 

receaveArguments{) 

Description 

Processes any arguments passed from a menu item or from dw.runCommand(),if 
any arguments were given to the dw . runCommand ( ) function. 

Arguments 

{argl}, {arg2},...{argN} 

If the a rguments attribute is defined for a menui tern tag, the value of that 
attribute is passed to the recei veArguments ( ) function (and to the 
can Accept Command ( ), i sCommandChecked ( ), and setMenuText ( ) functions) 
as one or more arguments. The a rguments attribute is useful for distinguishing 
between two menu items that call the same menu command. 

Returns 

Nothing. 
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setMenuTextQ 



Description 

Specifies the text that should appear in the menu. 

Note: Do not use this function if you are using getDynami eContent ( ) . 

Arguments 

largl }, {arg2},...{argN} 

If the a rguments attribute is defined for a men in tern tag, the value of 
that attribute is passed to the setMenuTextO function (and to the 
ca n Accept Comma nd( ), i s Comma n d C h ec ked ( ), and recei veArguments( ) 
functions) as one or more arguments. The a rguments attribute is useful for 
distinguishing between two menu items that call the same menu command. 

Returns 

The string that should appear in the menu. 

wmdowDsmensBonsO 

Description 

Sets specific dimensions for the Parameters dialog box. If this function is not 
defined, the window dimensions are computed automatically. 

Note: Do not define this function unless you want an Options dialog box larger than 
640 x 480 pixels. 

Arguments 

platform 

The value of the argument is either "maci ntosh " or " wi ndows ", depending on 
the users platform. 

Returns 

A string of the form "wi dth In Pixel s , hei ght In Pi xel s". 

The returned dimensions are smaller than the size of the entire dialog box because 
they do not include the area for the OK and Cancel buttons. If the returned 
dimensions do not accommodate all options, scroll bars appear. 

Example 

The following instance of wi ndowDi men si ons ( ) sets the dimensions of the 
Parameters dialog box to 648 x 520 pixels: 

function wi ndowDi mensi ons ( ) { 
return "648,520"; 

} 
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A simple menu command 



The following menu command is associated with two menu items: Undo 
and Redo. It checks the a rguments attribute of the menui tem tag and performs 
adw.undoO oradw.redoO operation depending on the value of the first (and 
only) argument. 

<HTML> 
<HEAD> 

<!-- Copyright 1999 Macromedia, Inc. All rights reserved. --> 

<TITLE>Edit CI i pboa rd</TITLE> 

<SCRIPT LANGUAGE^" Java script") 

function recei veArguments ( ) 

{ 

if (arguments . 1 ength != 1) return; 

var whatToDo = a rguments [0] ; 
i f (whatToDo == "undo" ) 
{ 

dw. undo( ) ; 

} 

else if (whatToDo == "redo") 
{ 

dw. redo( ) ; 

} 



function canAcceptCommand( ) 
{ 

var selarray; 

if (arguments . 1 ength != 1) return false; 
var bResul t = fal se ; 

var whatToDo = a rguments [0] ; 
i f (whatToDo = "undo" ) 
{ 

bResul t = dw. canUndo( ) ; 

} 

else if (whatToDo == "redo") 
{ 

bResul t = dw. canRedo( ) ; 

} 

return bResult; 

} 

function setMenuText ( ) 
{ 

if (arguments . 1 ength != 1) return ""; 

var whatToDo = a rguments [0] ; 
i f (whatToDo == "undo" ) 
return dw . getUndoText ( ) ; 
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else if (whatToDo == "redo") 

return dw . getRedoText ( ) ; 
el se return " " ; 

} 

</SCRIPT> 

</HEAD> 

<B0DY> 

</B0DY> 

</HTML> 

In this command, the recei veArguments ( ) function both processes the 
arguments and executes the command, but this need not be the case. More 
complex menu commands might call different functions to execute the command. 
For example, the following code checks whether the first argument is " f oo " ; if it 
is, it calls thedoOperationXO function and passes it the second argument. If the 
first argument is "bar", it calls thedoOperationYO function and passes it the 
second argument. doOperati onX( ) or doOperati onY( ) is responsible for 
executing the command. 

function recei veArguments () { 

if (arguments . 1 ength != 2) return; 

var whatToDo = a rguments [0] ; 

i f (whatToDo == "foo" ) { 

doOperati onX( a rguments [1] ) ; 
}else if (whatToDo == "bar"){ 

doOperati onX( a rguments [1] ) ; 

} 

} 
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A simple dynamic menu 



The following menu command does two things: It generates the Preview in 
Browser submenu, and it launches the current file (or the selected files in the 
Site window) in the browser that the user chooses from the submenu. 

<HTML> 
<HEAD> 

<!-- Copyright 1999 Macromedia, Inc. All rights reserved. --> 
<TITLE>Preview Browsers</TITLE> 
<SCRIPT LANGUAGE=" Java script") 

<!-- 

// getDynami eContent returns the contents of a dynamically 
// generated menu. 

// returns an array of strings to be placed in the menu, with a 
// unique 

// identifier for each item separated from the menu string by a 
// semicolon. 

// 

// return null from this routine to indicate that you are not 

// adding any 

// items to the menu 

f uncti on getDynami eContent ( i temID) 

{ 

var browsers = null; 
var PIB = null ; 
var i ; 
var j=0; 

var bUpdate = dw . getMenuNeedsUpdati ng( i teml D ) ; 

if (bUpdate) 
{ 

browsers = new Array ( ) ; 
PIB = dw. getBrowserLi st( ) ; 

// each browser pair has the name of the browser and the path 
// that leads 

// to the application on disk. We only put the names in the 
// menus. 

for Ci=0; i<PIB. length; i=i+2) 
{ 

browsers[j] = new Stri ng( PIB[i ] ) ; 

if (dw. getPrimaryBrowser( ) == PIB[i+l]) 

browsers[ j ] += "\tF12" ; 
if (navi gator . pi atform == "MacPPC") 
{ 

if (dw. getSecondaryBrowser( ) == PIB[i+l]) 
browsers[j] += "\t ?F12" ; 

} 

el se 
{ 

if (dw. getSecondaryBrowser( ) == PIB[i+l]) 
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browsers[j] += "\t Ctr1+F12"; 

} 

browsers[j] += " ; i d=' " + PI B[i ]+ ; 
J = J+l; 

} 

dw. noti fyMenullpdated( i tern ID , "dw . get Browser Li st( ) " ) ; 

} 

return browsers; 

} 

function canAcceptCommand ( ) 
{ 

var bHaveDocument ; 

if (dw.getFocus( ) == 'site') 

bHaveDocument = si te . getSel ecti on ( ) . 1 ength > 0; 
el se 

bHaveDocument = dw . getDocumentDOM( ' document ' ) != null; 
return bHaveDocument; 

} 

function recei veArguments ( ) 
{ 

var theBrowser = a rguments [0] ; 
if (dw. get Focus ( ) == 'site') 

dw. brows eDocument( si te . getSel ecti on( ) , theBrowser ) ; 
el se 

dw. browseDocument(dw. get Document Path ( ' document ' ) , theBrowser ) ; 
} 

// --> 

</SCRIPT> 

</HEAD> 

<B0DY> 

</B0DY> 

</HTML> 
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CHAPTER 6 

Reports 



You can use the reports API functions to create custom reports or modify the set 
of prewritten reports shipped with Dreamweaver. 

Reports are stored in the \ Configuration Reports folder. The Reports folder 
has subfolders representing report categories. Each report can belong to only 
one category. 

Each subfolder can have a file in it called _foldername.txt. If this file is present, its 
contents are used as the category name instead of the folder name. If this file is not 
present, the folder name is used. The category names are limited to 31 characters. 
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How reports work 



1 Reports are accessible through the Site > Reports... menu. When chosen, this 
menu item displays a dialog box from which the user selects reports to run on a 
choice of targets. 

2 The user selects which files to run the selected reports on using the Report On: 
menu. This menu contains Current Document, All Files in Current Local Site, 
Selected Files In Local Site, and Folder. When the Folder option is selected, a 
Browse button and edit field appear to let the user choose a folder. 

3 The user can customize reports that have parameters by choosing the Settings 
button, then entering values for the parameters. Each report is responsible for 
displaying its own Settings dialog box. This dialog box is optional; not every 
report will require the user to set the report's parameters. If a report does not 
have a Settings dialog box, then the Report Settings... button is dimmed when 
the report is selected in the list. 

4 After the reports are selected and their settings set, the user clicks the 
Run button. 

Each report that defines the bef ore Report i ng ( ) function has that function 
called before the reporting process begins. If a report returns fal se from this 
function, it is removed from the report run. 

5 Each file is passed to each report that was selected in the Reports 
dialog box using the process Fi 1 e ( ) function. If the report needs to 
include information about this file in the results list, it should call the 
dw.results.addResultltemO function. This process continues until all 
files pertaining to the user's selection have been processed, or the user clicks 
the Stop button in the bottom of the window. Dreamweaver displays the name 
of each file being processed and the number of remaining files to be processed. 

Each report that defines theendReportingO function has that function called 
after the reporting process completes. 

8 The results of each report process appear in a separate Results window. 
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The report API 



The only required function for the report API is the processFileO function. All 
other functions are optional. 

proeessFiieQ 

Description 

Called when there is a file to process. The Report command should process the 
file without modifying it and use the addResultltemO function to return 
information about the file. Dreamweaver automatically releases each file's DOM 
when finished. 

Arguments 

strFilePath 

strFi 1 ePa th is a fully qualified file path name of the file to process. 

Returns 

Nothing. 

beginReportmgC) 

Description 

Called at the start of the reporting process, before any reports are actually run. If 
the Report command returns fal se from this function, target is excluded from 
the report run. 

Arguments 

target 

target is a string indicating the target of the report session. It can be one of the 
following values: "CurrentDoc", "CurrentSi te", "CurrentSi teSel ecti on " 
(for the selected files in a site), or " Fol der : + the path to the folder the 
user selected" (for example, " Fol der : c : temp"). 

Returns 

true if the report has run successfully, f a 1 se if target is excluded from the 
report run. 
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endReportingQ 



Description 

Called at the end of the Report process. 

Arguments 

None. 

Returns 

Nothing. 

commandButtonsO 

Description 

Defines the buttons that should appear on the right side of the Options dialog box 
and their behavior when clicked. If this function is not defined, no buttons 
appear, and the BODY of the report file expands to fill the entire dialog box. 

Arguments 

None. 

Returns 

An array containing an even number of elements. The first element is a string 
containing the label for the topmost button. The second element is a string of 
JavaScript code that defines the behavior of the topmost button when clicked. 
Remaining elements define additional buttons in the same manner. 

Example 

The following instance of comma nd Button s ( ) defines three buttons: OK, Cancel, 
and Help. 

function commandButtons ( ) { 

return new ArrayCOK" , "doCommand ( ) " , "Cancel" 
"wi ndow. cl ose( ) " , "Help" , " showHel p( ) " ) ; 

} 



configureSettings(} 

Description 

Determines whether the Report Settings button should be enabled in the Reports 
dialog box when this report is selected. 

Arguments 

None. 

Returns 

true if the Report Settings button should be enabled, f al se otherwise. 
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wmciowDsmenssonsO 

Description 

Sets specific dimensions for the Parameters dialog box. If this function is not 
defined, the window dimensions are computed automatically. 

Note: Do not define this function unless you want an Options dialog box larger than 
640x480 pixels. 

Arguments 

pi atform 

The value of the argument is either "maci ntosh " or " wi ndows " , depending on 
the users platform. 

Returns 

A string of the form "wi dth In Pixel s , hei ght In Pixel s". 

The returned dimensions are smaller than the size of the entire dialog box because 
they do not include the area for the OK and Cancel buttons. If the returned 
dimensions do not accommodate all options, scroll bars appear. 

Example 

The following instance of wi ndowDi mensi ons ( ) sets the dimensions of the 
Parameters dialog box to 648 x 520 pixels: 

function wi ndowDi mensi ons () { 
return "648,520"; 

} 
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JavaScript Debugger Modules 



A JavaScript Debugger Module is a special type of extensibility module, which 
inserts special code into a document to interface with the JavaScript Debugger. 
The debugger modules are located with the Dreamweaver Program Files in the 
Configuration/Debugger subfolder. These modules insert specific JavaScript and 
HTML into a working document to create a "debug version" of the document the 
next time the JavaScript Debugger runs. The "debug version" is simply a set of 
temporary replicated files for the HTML document and each external JavaScript 
file, all created by Dreamweaver and saved in the current working folder. The 
debug version of the HTML file then appears in the browser. The JavaScript 
inserted into the temporary files, called "instrumentation", communicates with 
the Dreamweaver JavaScript Debugger as the JavaScript executes in the browser. 

For information about JavaScript Debugger API Commands, see "JavaScript 
Debugger functions" on page 304. 
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How the JavaScript Debugger Module works 



Dreamweaver comes with two debugger modules, one for each 
supported browser: Netscape and Internet Explorer. To provide support 
for a different browser, you would create a new debugger module, and then 

use dom. i instrument Document and dreamweaver . sta rt Debugger to debug 
the document in the other browser. 

When you call dom. i nst rumentDocument, the specified debugger module 
receives callbacks as Dreamweaver parses the JavaScript in the document. So, 
for instance, you could create a debugger module that inserts comments or 
records information about the JavaScript code, instead of inserting debugging 
enhancements. 

When dom. i nstrumentDocument is called with a specific debugger module, the 
following steps occur: 

1 Dreamweaver calls getlncl udeFi 1 es( ) in the debugger mo dule. This 
function returns the list of files that will be referenced from HTML 
instrumentation code returned from getHeadlnstrumentO and 
getBodylnstrumentO (which are called later). The include files can be 
any type of file, such as an external JavaScript file or JavaApplet or ActiveX 
control. All of the files must be in the Configuration/Debugger subfolder 
with the Debugger Module. Dreamweaver will copy the include files to the 
directory that contains the file being debugged, and then later will delete 
the include files from that directory when Dreamweaver exits. 

2 Next, the HTML document is scanned for script tags and event handlers. The 
code inside the script tag, in an external JavaScript file, or in an event handler is 
known as a block. 

Note: An external JavaScript file is a file that is specified as the "src" attribute of a 
SCRIPT tag. 

3 Dreamweaver parses script tags in the HEAD section first. 

4 When Dreamweaver finds a script tag or event handler, it calls the debugger 
module's startBlockO function and passes in the name of the file and the 
line and character offsets from the beginning of the file. 

5 Then Dreamweaver begins parsing the JavaScript code in the block. 

6 When Dreamweaver finds a JavaScript statement, such as a variable declaration, 
it calls getStep Instrument ( ) passing the line and character offsets and other 
information. The debugger module returns a string of JavaScript code that is 
inserted before the statement. You must take care to return valid JavaScript 
code. For each call to getStep Instrument ( ), Dreamweaver records the line 
number as a valid breakpoint line regardless of what instrumentation is 
returned. So, when the debugger is started with dw.startDebugger(),the 
breakpoints the user has already set will be moved to one of these valid lines. 
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7 When Dreamweaver finds a function declaration, it calls the 
getFuncti onStartInstrument( ) to receive the instrumentation 
to be inserted at the beginning of the function. 

Note: This is not considered a valid breakpoint line. 

8 Dreamweaver continues parsing the function and calling 
getStepInstrumenK ) for each statement in the function. 

9 When Dreamweaver comes to a return statement, or the end of the function, 
it calls getFuncti on End Instilment ( ) to receive the instrumentation to be 
inserted before the function returns. 

Note: This is not considered a valid breakpoint line. 

10 If Dreamweaver encounters a syntax error or warning in the JavaScript block, 
it calls reportError( ) or reportWarni ng( ), respectively. After an error is 
encountered, Dreamweaver stops parsing the block. Other blocks will still 
be parsed. 

11 After Dreamweaver has parsed all the script blocks in the HEAD section, it calls 
getHeadlnstrumentO to get the HTML instrumentation to insert in the 
HEAD section. 

Note: This function should return HTML, not JavaScript. If the debugger module needs 
to insert JavaScript code in the HEAD, it must enclose it in a SCRIPT tag. 

12 Next Dreamweaver begins processing the JavaScript blocks (SCR I PT tags and 
event handlers) in the BODY section of the document. 

13 After the last block in the BODY section is instrumented, Dreamweaver calls 
getBodylnstrumentO to get the HTML instrumentation to insert in the 
BODY section. 

Note: This function should return HTML, not JavaScript. 

14 After Dreamweaver calls getBodylnstrumentO, there is one final call to 
startBl ock( ) and getStepInstrument( ) for an auto-breakpoint. The 
instrumentation does not correspond to any user-defined SCR I PT tag, but 
rather is inserted in a new SCR I PT tag after the BODY instrumentation. Unlike 
other calls to getStepInstrument ( ), this line is not considered a valid line on 
which the user can set a breakpoint, but rather it is treated as a special kind of 
breakpoint at which the debugger always stops. 

15 Finally, Dreamweaver calls get On Un 1 oad Instrument ( ) to get JavaScript 
instrumentation to be inserted in the onlJnl oad handler of the BODY tag. If the 
document already has an onUnload handler, this instrumentation is inserted 
after the user-defined onUnl oad code. 
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The JavaScript Debugger Module API 

The JavaScript Debugger Module API allows you to customize the way the debug 
version of a document is created. You would need to create a debugger module if 
you wanted to make the Dreamweaver JavaScript Debugger work with a browser 
other than the two (Netscape and Internet Explorer) for which Dreamweaver 
already provides support. You could also create a debugger module for some other 
specialized purpose, such as counting the number of JavaScript statements used by 
a particular document. 

Note: Currently only SCRIPT tags and event handlers are parsed for instrumentation. 
There are some other ways to use JavaScript in HTML documents, such as JavaScript 
URLs, JavaScript entities, and conditional comments. These are not currently supported. 

The JavaScript Debugger Module API functions are significant only in the 
context of debugger module files. Specifically, Dreamweaver automatically calls 
the getStepInstrumentO function if it is defined in the debugger module file. 
For any other extension file, a function named getStepInstrumentO acts like 
a user-defined function — you have to call it explicitly. 

As opposed to the way you work with the functions in the main JavaScript API, 
you are responsible for writing the body of each function and returning a value, 
if required, for the debugger modules. For the functions in the main API, you call 
and pass arguments, and Dreamweaver generates return values, if any. For the 
debugger modules, Dreamweaver calls the functions and passes arguments to 
them, and you generate return values, if any. 

All of the JavaScript Debugger Module functions are optional. If a function is not 
defined, then nothing happens when Dreamweaver calls it. 

getFunctsonEnd^nstrumentQ 

Availability 

Dreamweaver 4.0 

Description 

Called after the last statement in a function declaration. If any return statements 
exist, then this module is called to insert instrumentation after the return value is 
evaluated and before the function will return strings. 

Arguments 

None. 

Returns 

A string containing the JavaScript to insert at the end of the function. 
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getFunctionStartfnstrumentO 

Availability 

Dreamweaver 4.0 

Description 

Called before the first statement in a function declaration. The 
getStepInstrumentO function is also called for the statement. 

Arguments 

None. 

Returns 

A string containing the JavaScript to insert at the beginning of the function. 

getBodyfnstrumentO 

Availability 

Dreamweaver 4.0 

Description 

This function is called exactly once after all blocks in the HEAD section have been 
instrumented. 

Arguments 

None. 

Returns 

A string containing HTML to insert at the top of the <B0DY> section. 

getHeadSnsirumeniQ 

Availability 

Dreamweaver 4.0 

Description 

This function is called exactly once after all blocks in the HEAD section are 
instrumented, but before the BODY section blocks are instrumented. 

Arguments 

None. 

Returns 

A string containing HTML to insert at the top of the <HEAD> section. 
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getSndudedFaSeUstQ 



Availability 

Dreamweaver 4.0 

Description 

Called to get a list of files that are referenced by code inserted in the head or 
body (from the getHead Instrument ( ) and getBody Instrument ( ) functions). 
These files must be located in the Configuration/Debugger directory of the 
Dreamweaver Program Files with the instrumentation debugger module. 

Arguments 

None. 

Returns 

An array of file names that should be copied to the directory with the 
instrumented file. 

getOnUntoadlnstrumentQ 

Availability 

Dreamweaver 4.0 

Description 

This function is called exactly once after getHead Instrument ( ) is called. 

Arguments 

None. 

Returns 

String containing JavaScript to insert at the end of the onUnl oad event handler of 
the BODY tag. 

getSteptostrumentQ 

Availability 

Dreamweaver 4.0 

Description 

Called for each statement that is parsed inside a block. A call is always made to 
Sta rtBl ock( ) before this function is called. Dreamweaver records each line for 
which it calls this function as a valid breakpoint line. While the debugger is 
started, all breakpoints are moved to valid breakpoint lines. 
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Arguments 

1 i neNumber, offset, bisInFuncton 

• 7 / neNumber is the line number of the next statement relative to the start of the 
block (1 -based index). 

• offset is the offset of the first character of the next statement relative to the 
start of the block (0-based index). 

• bi s I nFuncti on is a Boolean that indicates if the step is in a function definition 
(true) or in the global scope (fal se). 

Returns 

A string containing the JavaScript code to insert before the statement. 

reportErrorQ 

Availability 

Dreamweaver 4.0 

Description 

Called when a syntax error is detected. The errors and warnings are not necessarily 
reported in order. 

Arguments 

fileName, errorNumber, strDesc, li neNumber, offset 

• fi leName is the name of the file. 

• errorNumber is the numeric identifier of the error that occurred. 

• st rDesc is the description of the error. 

• 7 i neNumber is the line number in which the error occurred, relative to the start 
of the block. 

• offset Is the offset of the character at which the error occurred, relative to the 
start of the block. 

Returns 

Nothing. 
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reportWarningO 

Availability 

Dreamweaver 4.0 

Description 

Called when a warning is detected in the file. 
Arguments 

fileName, errorNumber, strDesc, 1 i neNumber, offset 

• flleHame Is the name of the file. 

• erro rNumb e r is the numeric identifier of the warning that occurred. 

• st rDes c is the description of the warning. 

• 7 i neNumber is the line number in which the warning occurred, relative to the 
start of the block. 

• offset is the offset of the character at which the warning occurred, relative to 
the start of the block. 

Returns 

Nothing. 

startBlockQ 

Availability 

Dreamweaver 4.0 

Description 

Indicates the beginning of a new block of JavaScript code. The block can be a 
script tag, event handler, or external .js file. 

Arguments 

fileName, li neNumber, offset 

• f / / eName is the name of the HTML document or .js file containing the block. 
The location is specified by a relative path to the source HTML document. 

• / / neNumber is the line number in the HTML document or .js file in which the 
block begins (1 -based index). 

• o ffs e t is the offset of the first character of JavaScript code from the beginning 
of the file (0-based index). 

Returns 

Nothing. 
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Property Inspectors 



The Property inspector is perhaps the most familiar floating panel in the 
Dreamweaver interface. It is indispensable for defining, reviewing, and 
changing the name, size, appearance, and other attributes of the selection, as 
well as for launching internal and external editors for the selected element. 

Dreamweaver has several built-in interfaces for the Property inspector that let 
you set properties for many standard HTML tags. (These built-in inspectors 
are part of the core Dreamweaver code; for this reason, you will not find 
corresponding Property Inspector files for them in the Configuration folder.) 
With custom Property Inspector files, you can override these built-in interfaces 
or create new ones to inspect custom tags. 
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Custom Property Inspector files are HTML files that reside in the Configuration/ 
Inspectors folder inside the Dreamweaver application folder. The first line of a 
Property Inspector file (the line above the opening HTML tag) must be a comment 
in the following format: 

<!-- 

tag : tagNameOrKeyword , priori ty : 1 toifl, sel ecti on : exactOrtti thi n ,hl i ne 
, v 1 i n e - - > 

where: 

• tagNameOrKeyword is the tag to be inspected or one of the following 
keywords: ^COMMENT* (for comments), *L0CKED* (for locked regions), or 
*ASP* (for ASP tags). 

• 1 to 10 is the priority of the Property Inspector file: 1 indicates that this 
inspector should be used only when no others can inspect the selection; 10 
indicates that this inspector takes precedence over all others that can inspect 
the selection. 

• exactOrk/i thi n indicates whether the selection can be within the tag (within) 
or must exactly contain the tag (exact). 

• hi i ne (optional) indicates that a horizontal gray line should appear between 
the upper and lower halves of the inspector in expanded mode. 

• vl i ne (optional) indicates that a vertical gray line should appear between the 
tag name field and the rest of the properties in the inspector (see the image 
Property inspector for an example). 

The following comment would be appropriate for an inspector that is designed to 
inspect the HAPPY tag: 

<!-- tag:HAPPY, pri ori ty : 8 , sel ecti on : exact , hi i ne , vl i ne --> 

The BODY of a Property Inspector file contains an HTML form. Instead of 
displaying the form contents in a dialog box, however, Dreamweaver uses the 
form to define the input areas and layout of the inspector. 
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How Property Inspector files work 

At startup, Dreamweaver reads the first line of each .htm and .html file in the 
Configuration/ Inspectors folder, looking for the comment string that defines the 
type, priority, and selection type of a Property inspector. Files that do not have this 
comment as their first line are ignored. 

When the user makes a selection in Dreamweaver or moves the insertion point to 
a different location, the following chain of events occurs: 

1 Dreamweaver looks for any inspectors that have a selection type of within. 

2 If there are any within inspectors, Dreamweaver searches up the document 
tree from the currently selected tag to check whether there are inspectors 
for any tags that surround the selection. If — and only if — there are no 
within inspectors, Dreamweaver looks for any inspectors that have a 
selection type of exact. 

3 For the first tag found that has one or more inspectors, Dreamweaver calls 
each inspector's canlnspectSelectionO function. If this function returns 
fal se, Dreamweaver no longer considers the inspector a candidate for 
inspecting the selection. 

4 If more than one potential inspector remains after calling 

canlnspectSelectionO, Dreamweaver sorts the remaining 
inspectors by priority. 

5 If more than one potential inspector shares the same priority, Dreamweaver 
chooses an inspector alphabetically by name. 

8 The chosen inspector appears in the Property Inspector floating panel. If the 
Property Inspector file defines the di spl ayHel p ( ) function, a small ? icon is 
displayed in the upper right corner of the inspector. 

7 Dreamweaver calls the i n s p e c t S e 1 e c t i o n ( ) function to gather info rmation 
about the current selection and populate the inspectors fields. 

8 Event handlers attached to the fields in the Property inspector interface execute 
as the user encounters them. (For example, you may have an onBl ur event that 
calls setAtt ri bute ( ) to set an attribute to the value just entered by the user.) 
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The Property inspector API 



Two of the Property inspector API functions (canlnspectSelectionO and 
i nspectSel ecti on ( )) are required. The Property inspector API functions differ 
from the functions in the main JavaScript API in three ways: 

• They are not methods of the d reamwea ver, dom, or si te object. 

• They are significant only in the context of Property Inspector files. That is, 
Dreamweaver automatically calls thecanlnspectSelectionO function in a 
Property Inspector file, whereas a function named canlnspectSelectionO 
acts like a user-defined function in any other extension file — you have to 
call it explicitly. 

• You are responsible for writing the body of each function and returning a value, 
if required. This is the opposite of how the functions work in the main API: 
those you call and pass arguments to, and Dreamweaver generates return 
values, if any. Here Dreamweaver calls the functions and passes arguments to 
them, and you generate return values, if any. 

canlnspectSelectionO 

Description 

Determines whether the Property inspector is appropriate for the 
current selection. 

Arguments 

None. 

Use dom.getSelectedNodeO to get the current selection as a JavaScript object. 
Returns 

true if the inspector can inspect the current selection; fa 1 se if it cannot. 
Example 

The following instance of can I nspectSel ecti on( ) returns true if the 
selection contains the CLASS I D attribute and the value of that attribute is 

"cl si d : D27CDB6E-AE6D-llcf -96B8-444553540000" (the class ID for 
Flash Player): 

function can I nspectSel ecti on ( ) { 

var theDOM = dw . getDocumentDOM( ) ; 

var theObj = theDOM . getSel ectedNode( ) ; 

return ( theObj . nodeType == Node . ELEMENT_NODE && - 

theObj . hasAttri bute( "cl assi d" ) && -> 

theObj . getAttri but e( "cl assi d H ) . toLowerCase( )== -< 

"clsid:D27CDB6E-AE6D-llcf-96B8-444553540000") ; 
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displayHelpQ 



Description 

If this function is defined, a ? icon appears in the upper right corner of the 
Property inspector. This function is called when the user clicks the icon. 

Arguments 

None. 

Returns 

Nothing. 

Example 

The following instance ofdisplayHelpO opens a file in a browser window that 
explains the fields in the Property inspector: 

function di spl ayHel p( ) { 

dreamweaver . browse Documents ' http : //www. hooha.com/dw/^ 
i nspectors/i nspHel p. html' ) ; 

} 

inspectSelectionQ 

Description 

Refreshes the contents of the user input fields based on the attributes of the 
current selection. 

Arguments 

maxOrMin 

The argument is either max or mi n, depending on whether the Property inspector 
is in its expanded or contracted state. 

Returns 

Nothing. 

Example 

The following instance ofinspectSelectionO gets the value of the 
CONTENT attribute and uses it to populate a form field called keywords: 

function i nspectSel ecti on ( ) { 

var dom = dreamweaver . getDocumentDOMC ) ; 
var theObj = dom. getSel ectedNode( ) ; 
document . forms[0] . keywords . val ue = -i 
theObj . get Attn' bute( "content" ) ; 

} 
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A simple Property inspector example 



The following Property inspector inspects a fictional tag called I NT J. The I NT J tag 
is empty (that is, it has no closing tag), so its selection type is exact. As long as 
the selection is exactly an I NT J tag, the Property inspector should show up — 
so the can InspectSel ecti on ( ) function returns true every time. To have a 
different inspector appear depending on the value of the I NT J tag's TY PE attribute, 
for example, thecanlnspectSelectionO function must check the value of the 
TYPE attribute to determine which Property inspector is the right one. (This is 
how the keywords and description Property inspectors work, because "keywords" 
and "description" are not tags but values of the META tags NAME attribute.) 

<!-- tag : INTJ ,pri ori ty : 5 , sel ecti on : exact , vl i ne , hi i ne --> 

<HTML> 

<HEAD> 

<TITLE>Inter jecti on Inspector</TITLE> 
<SCRIPT LANGUAGE^" JavaScript") 

function can InspectSel ecti on ( ) { 
return true; 

} 

function i nspectSel ecti on ( ) { 

// Get the DOM of the current document 
var theDOM = dw . getDocumentDOM( ) ; 
// Get the selected node 
var theObj = theDOM . getSel ectedNode( ) ; 

// Get the value of the TYPE attribute on the INTJ tag 

var theType = theObj . getAttri bute( ' type ' ) ; 

// Initialize a variable called typelndex to -1. This will be 

// used to store the menu index that corresponds to 

// the value of the TYPE attribute 

var typelndex = -1 ; 

// If there was a TYPE attribute 
if (theType) { 

// If the value of TYPE is "jeepers", set typelndex to 0 
if (theType . toLowerCase( ) == "jeepers"){ 
typelndex = 0; 

// If the value of TYPE is "jinkies", set typelndex to 1 
}else if (theType . toLowerCase( ) == "jinkies"){ 
typelndex = 1 ; 

// If the value of TYPE is "zoinks", set typelndex to 2 
}else if (theType . toLowerCase( ) == "zoinks"){ 
typelndex = 2; 

} 

} 

// If the value of the TYPE attribute was "jeepers", 
// "jinkies", or "zoinks", choose the corresponding 
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// option from the pop-up menu in the interface 
if (typelndex != -1){ 

document . top Layer . document . top Layer Form . i ntType 
sel ectedlndex = typelndex; 

} 



function set Inter jecti onTag( ) { 

// Get the DOM of the current document 
var theDOM = dw . getDocumentDOM( ) ; 
// Get the selected node 
var theObj = theDOM . getSel ectedNode( ) ; 

// Get the index of the selected option in the pop-up menu 
// in the interface 

var typelndex = document . topLayer . document .-> 

top Lay e r Fo rm. i ntType . sel ectedlndex; 
// Get the value of the selected option in the pop-up menu 
// in the interface 

var theType = document . topLayer . document . topLayerForm 

i ntType . opti on s[ type Index] . val ue ; 

// Set the value of the TYPE attribute to theType 
theObj . set Attn" bute( ' type ' , theType) ; 

} 

</SCRIPT> 
</HEAD> 

<B0DY> 

<SPAN ID="image" STY LE=" posi ti on : absol ute ; width:23px; 
height:17px; z-index:16; left: 3px; top: 2px"> 
<IMG SRCX'interjection.gif" WIDTH="36" HEIGHT="36" 
NAM E=" i nter jecti on Image") 
</SPAN> 

<SPAN ID="label" STYLE="posi ti on : absol ute ; width:23px; 
height:17px; z-index:16; left: 44px; top: 5px"> Inter jecti on</SPAN> 

<!-- If your form fields are in different layers, you must 
create a separate form inside each layer and reference it as 
shown in the i nspectSel ecti on ( ) and set Inter jecti onTag( ) 
functions above. --> 

<SPAN I D="topLayer" STY LE=" pos i ti on : absol ute ; z-index:l; 
left: 125px; top: 3px; width: 431px; height: 32px"> 
< FO RM NAME="topLayerForm"> 

<TABLE B0RDER="0" CELLPADDI NG="0" CELLSPACING="0"> 
<TR> 

<TD VALIGN="baseline" A L I G N = " r i ght ">Type : </TD> 
<TD VALIGN="baseline" ALIGN=" ri ght "> 
< S E LECT NAME="intType" STYLE="wi dth : 86" 
onChange=" set Inter jecti onTag( ) "> 
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<OPTION VALUE="jeepers">Jeepers</OPTION> 

<OPTION VALUE="jinkies">Jinkies</OPTION> 

<OPTION VALUE= M zoinks">Zoinks</OPTION> 

</SELECT> 

</TR> 

</TABLE> 

</FORM> 

</SPAN> 

</BODY> 
</HTML> 
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CHAPTER 9 

Floating Panels 



You can create any kind of floating panel or inspector without the size and layout 
limitations of Property inspectors. 

A custom Property inspector should still be your first choice for setting the 
properties of the current selection. However, custom floating panels offer more 
room and flexibility for displaying information about the entire document or 
multiple selections. 

Dreamweaver already has several built-in floating panels that are accessible 
from the Window menu; you can add your own panels to this menu using the 
extensible menus feature. (These built-in panels are part of the core Dreamweaver 
code; for this reason, you will not find corresponding Floating Panel files for them 
in the Configuration folder.) For more information on adding items to the menu 
system, see "Customizing Dreamweaver," in Using Dreamweaver. 

Custom Floating Panel files are HTML files that reside in the Configuration/ 
Floaters folder inside the Dreamweaver application folder. The BODY of a Floating 
Panel file contains an HTML form; event handlers attached to form elements may 
call JavaScript code that performs arbitrary edits to the current document. 



77 



How Floating Panel fifes work 



Custom floating panels can be moved, resized, and tabbed together just like the 
floating panels that are built into Dreamweaver. Custom floating panels differ 
from built-in floating panels in the following ways: 

• It is not possible to display an icon in the tab of a custom floating panel; the tab 
always shows the contents of the floating panel's TITLE tag. 

• Custom floating panels display in the default gray. Setting the BGCOLOR 
attribute in the BODY tag has no effect. 

• All custom floating panels either appear always on top of the Document 
window or float behind it when inactive, depending on the setting for All 
Other Floaters in the Floating panels preferences. 

Floating Panel files also differ somewhat from other extensions. Unlike other 
extension files, Dreamweaver does not load Floating Panel files into memory at 
startup unless the floating panels were visible when Dreamweaver last shut down. 
If the floating panels were not visible when Dreamweaver last shut down, the files 
that define them are loaded only when referenced from one of the following 
functions: dreamwea ver . getFl oaterVi si bi 1 i ty( ), 

dreamweaver . setFl oaterVi si bi 1 i ty( ), or dreamwea ver . toggl eFl oater( ). 

When one of the files inside the Configuration folder calls 

dw. getFl oaterVi si bi 1 i ty( fl oaterName), 
dw. set Fl oaterVi si bi 1 i ty( fl oaterName), or 

dw. toggl eFl oater( fl oaterName), the following chain of events occurs: 

1 If fl oaterName is not one of the reserved floating panel names, 
Dreamweaver searches the Configuration/Floaters folder for a file called 

fl oaterName.hxm. (For a complete list of reserved floating panel names, see 
"dreamweaver. getFloaterVisibilityO" on page 450.) If fl oaterName.htm is 
not found, Dreamweaver searches for f 1 oat erH 3 me. html. If no file is found, 
nothing further happens. 

2 If the Floating Panel file is being loaded for the first time, the 

initial P o s i t i o n ( ) function is called, if defined, to determine the floating 
panels default position on the screen, and the i ni ti a 1 Tabs ( ) function is 
called, if defined, to determine the floating panels default tab grouping. 

3 The sel ecti onChanged( ) and document Edi ted ( ) functions are called on 
the assumption that changes probably occurred while the floating panel 
was hidden. 
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4 When the floating panel is visible, the following things happen: 

• When the selection changes, the select ionChangedO function is called, 
if defined. 

• When the user makes changes to the document, thedocumentEditedO 
function is called, if defined. 

• Event handlers attached to the fields in the floating panel interface execute 
as the user encounters them. (For example, a button with an on CI i ck event 
handler that calls dw . getDocumentDOM( ) . body . i nnerHTML=' ' would 
remove everything between the opening and closing BODY tags in the 
document when clicked.) 

5 When the user quits Dreamweaver, the current visibility, position, and tab 
grouping of the floating panel are saved. The next time Dreamweaver starts 
up, it loads the Floating Panel files for any floating panels that were visible at 
the last shutdown and displays the floating panels in their last position and 
tab grouping. 

The floating panel API 

The custom functions in the floating panel API are all optional. These functions 
differ from the functions in the main JavaScript API in three ways: 

• They are not methods of the dreamweaver, dom, or site object. 

• They are significant only in the context of Floating Panel files. That is, 
Dreamweaver automatically calls the document Ed i ted ( ) function if it is 
defined in a Floating Panel file, whereas a function named documentEditedO 
acts like a user-defined function in any other extension file — you have to call 
it explicitly. 

• You are responsible for writing the body of each function and returning a value, 
if required. This is the opposite of how the functions work in the main API: 
those you call and pass arguments to, and Dreamweaver generates return 
values, if any. Here Dreamweaver calls the functions and passes arguments 

to them, and you generate return values, if any. 
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displayHelpQ 



Description 

If this function is defined, a Help button appears below the OK and Cancel 
buttons in your dialog box. This function is called when the user clicks the 
Help button. 

Arguments 

None. 

Returns 

Nothing. 

Example 

The following instance ofdisplayHelpO opens in a browser window a file 
with instructions: 

function di spl ayHel p( ) { 

dreamweaver . brows eDocument( ' http: //www. hotwi red . com/^ 
webmonkey/ ja vase ri pt? /code_l i bra ry/wm_pos2_el mnt_dw/^ 
?tw=javascri pt ' ) ; 

} 



documentEditedQ 

Description 

Called when the floating panel becomes visible and after the current series of 
edits is complete — that is, multiple edits may occur before this function is called. 
This function should be defined only if the floating panel must track edits to 
the document. 

Note: Define document Ed i ted ( ) only if you absolutely require it because its existence 
impacts performance. 

Arguments 

None. 

Returns 

Nothing. 
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Example 

The following instance ofdocumentEditedO scans the document for layers and 
updates a text field that displays the number of layers in the document: 

function documentEdi ted ( ) { 

/* create a list of all the layers in the document */ 
var theDOM = dw. getDocumentDOM( ) ; 

var layersInDoc = theDOM . get El ementsByTagName( " 1 ayer" ) ; 
var layerCount = 1 ayersInDoc . 1 ength ; 

/* update the numOfLayers field with the new layer count */ 
document. theForm. numOf Layers . val ue = layerCount; 

} 

initsaiPosatk>n() 

Description 

Determines the initial position of the floating panel the first time it is called. If 
this function is not defined, the default position is the center of the screen. 

Arguments 

pi at form 

Possible values for plat fo rm are "Mac" and "Win". 
Returns 

A string of the form "1 eftPosInPixel s , topPos I n Pi xel s". 
Example 

The following instance of initial P o s i t i o n ( ) specifies that the first time the 
floating panel appears, it should be 420 pixels from the left and 20 pixels from the 
top in Windows, and 390 pixels from the left side of the screen and 20 pixels from 
the top of the screen on the Macintosh: 

function ini tial Posi tion(pl atform) { 
var initPos = "420,20" ; 
if (platform == "macintosh")! 
initPos = "390,20"; 

} 

return initPos; 

} 
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initialTabsQ 



Description 

Determines which other floating panels are tabbed together with this one the 
first time the floating panel appears. If any listed floating panel has appeared 
previously, it is not included in the tab group. Thus, to ensure that two custom 
floating panels are tabbed together, each should reference the other in each 
i n i t i a 1 Ta b s ( ) function. 

Arguments 

None. 

Returns 

Astring of the form "fl oaterNamel ,fl oaterName2, . . . fl oaterNameN". 
Example 

The following instance of i n i t i a 1 Ta bs ( ) specifies that the first time the floating 
panel appears, it should be tabbed together with the scriptEditor floating panel: 

function i ni ti al Tabs ( ) { 
return "scriptEditor"; 

} 

isAvaHabIeinCodeView() 

Description 

Defined by a floating panel to determine whether the floating panel should 
be enabled when focus is in the Code view. If this function is not defined, the 
floating panel is disabled in the Code view. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the floating panel should be enabled. 

selectionChangedQ 

Description 

Called when the floating panel becomes visible and when the selection changes 
(when focus switches to a new document or when the insertion pointer moves to a 
new location in the current document). This function should be defined only if 
the floating panel must track the selection. 

Note: Define selectionChangedO only if you absolutely require it because its 
existence impacts performance. 
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Arguments 

None. 

Returns 

Nothing. 

Example 

The following instance ofselectionChangedO shows a different panel (layer) 
in the floating panel depending on whether the selection is a script marker or 
something else: 

function sel ecti onChanged ( ) { 
/* get the selected node */ 
var theDOM = dw . getDocumentDOM( ) ; 
var theNode = dw . getSel ectedNode( ) ; 

/* check to see if the node is a script marker */ 

if (theNode. nodeType == Node . ELEMENT_NODE && theNode.- 

tagName == "SCRIPT")! 

document . 1 ayers[ ' bl ankl ayer ']. vi si bi 1 i ty = 'hidden'; 
document. layers[' sen" ptlayer']. visibility = 'visible'; 
}el se{ 

document. layers['scriptlayer']. visibility = 'hidden'; 
document. layers['bl ankl ayer']. visibility = 'visible'; 

} 



About performance 

Declaring the sel ecti onChanged ( ) or documentEdi ted( ) function in your 
custom floating panels risks adversely impacting Dreamweaver performance. 
Consider that documentEdi ted ( ) is called after every keystroke, and 
selectionChangedO is called after every press of an arrow key if Dreamweaver 
has been idle for more than one-tenth of a second. It's important to test your 
floating panel against many different scenarios, using large documents (100K 
or more of HTML) whenever possible. 

To help you avoid performance penalties, setTi meout ( ) was implemented as a 
global method in Dreamweaver 3. As in the browsers, setTi meout ( ) takes two 
arguments: the JavaScript to be called and the amount of time in milliseconds to 
wait before calling it. 

The setTi meout ( ) method lets you build pauses into your processing during 
which the user can continue interacting with the application. You must build in 
these pauses explicitly because the screen freezes while scripts are processing, 
preventing the user from performing further edits (and you from updating the 
interface or the floating panel). 
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The following code is from a floating panel that displays information about 
every layer in the document. It uses setTi meout ( ) to pause for half a second 
after processing each layer: 

/* create a flag that specifies whether an edit is being -< 

processed, and set it to false. */ 
document . runni ng = false; 

/* this function called when document is edited */ 
function documentEdi ted ( ) { 

/* create a list of all the layers to be processed */ 

var dom = dw . getDocumentDOM( ) ; 

document . 1 ayers = dom.getEl ementsByTagName( "1 ayer" ) ; 
document . numLayers = document . 1 ayers . 1 ength ; 
document . numProcessed = 0; 

/* set a timer to call processLayer ( ) ; if we didn't get 

* to finish processing the previous edit, then the timer 

* is al ready set . */ 

if (document . runni ng = false){ 

setTi meout ( "processLayer ( ) " , 500) ; 

} 

/* set the processing flag to true */ 
document . runni ng = true; 

} 

/* process one layer */ 
function processLayer () { 

/* display information for the next unprocessed layer, 
di spl ayLayer( ) is a function you would write to 
perform the "magic" . */ 
di spl ayLayer( document . 1 ayers [document . numProcessed] ) ; 

/* if there's more work to do, set a timeout to process 

* the next layer. If we're finished, set the document . runni ng 

* flag to false. */ 

document . numProcessed = document . numProcessed + 1; 
if (document . numProcessed < document . numLayers ) { 

setTi meout ( "processLayer ( ) " , 500) ; 
}el se{ 

document . runni ng = false; 

} 
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A sample floating panel example 

The following floating panel contains a text field that shows the contents of the 
selected Script marker (the yellow icon that appears in the Document window to 
mark the location of a script). If no Script marker is selected, a layer that contains 
thetext(no script sel ected ) appears. 

<html> 
<head> 

<title>Script Edi tor</ti tl e> 
<scri pt 1 anguage=" Java Sen pt"> 

function sel ecti onChanged ( ) { 
/* get the selected node */ 
var theDOM = dw . getDocumentDOM( ) ; 
var theNode = theDOM . getSel ectedNode( ) ; 

/* check to see if the node is a script marker */ 

if (theNode. nodeType == Node . ELEMENT_NODE && theNode.- 

tagName == "SCRIPT" ){ 

document. layersE'scriptl ayer']. visibility = 'visible'; 

document . 1 ayers[ ' scriptl ayer ' ] . document . the Form . scri ptCode .-> 

value = theNode . i nnerHTML; 

document . 1 ayers[ ' bl ankl ayer ']. vi si bi 1 i ty = 'hidden'; 
}el se{ 

document. layersE'scriptlayer']. visibility = 'hidden'; 
document . 1 ayers [' bl ankl ayer ']. vi si bi 1 i ty = 'visible'; 

} 

} 

/* update the document with any changes made by 

the user in the textarea */ 
function updateScri pt ( ) { 

var theDOM = dw . getDocumentDOM( ) ; 

var theNode = dw . getSel ectedNode( ) ; 

theNode . i nnerHTML = document . 1 ayersE ' scri ptl ayer '] .-> 

document . the Form . scri ptCode . val ue ; 



</scri pt> 
</head> 

<body> 

<div i d="bl ankl ayer " styl e="posi ti on : absol ute ; width:422px; 

hei ght : 181px ; z-index:l; left: 8px; top: llpx; 

visibility: hidden") 

<center> 

<br> 

<br> 

<br> 

<br> 

<br> 
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(no script selected) 

</center> 

</div> 



<div i d="scri ptl ayer" styl e="posi ti on : absol ute ; wi dth : 422px ; 
hei ght : 181px ; z-index:l; left: 8px; top: llpx; -< 
visibility: visible") 
<form name="theForm"> 

<textarea name=" scri ptCode" cols="80" rows="20" wrap=" V I RTUAL" 

onBl ur=" update Scri pt( ) "></ text area) 

</form> 

</div> 

</body> 
</html> 

Remember that it is not sufficient to save this code in a file called 

scriptEditor.htm in the Configuration/ Floaters folder; you must 

also call dw. setFl oaterVi si bi 1 i ty ( ' scri ptEdi tor ' , true) or 

dw. toggl eFl oater( ' scri ptEdi tor ' ) from somewhere in order to load 

the floating panel and make it visible. The most obvious place from which to 

do this is the Window menu in the menus.xml file. The menui tern tag might 

look like this: 

<menuitem name="Scri pt Editor" enabl ed=" true" 
comma nd="dw. toggl eFl oater( ' scri ptEdi tor ' ) " 
checked="dw. getFl oaterVi si bi 1 i ty ( ' scri ptEdi tor ' ) " /> 
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CHAPTER lO 

Behaviors 



Behaviors let nonprogrammers make their HTML pages interactive. They offer 
Web designers an easy way to assign actions to page elements by filling in an 
HTML form. 

You should write behavior actions when you want to share functions with 
nonprogrammers, or when you want to insert the same JavaScript function 
repeatedly but change the parameters each time. 

Note: You cannot use behaviors to insert VBScript functions directly; however, you can 
add a VBScript function indirectly by editing the DOM in the appl yBeha vi or ( ) function. 

The term behavior refers to the combination of an event (such as on CI i ck, 
on Load, or onSubmi t) and an action (for example, Check Plugin, Go to 
URL, Swap Image). The browser determines which HTML elements accept 
which events. Files listing events that each browser supports are stored in 
the Configuration/Behaviors/Events folder within the Dreamweaver 
application folder. 

Actions are the part of a behavior you have control over; thus, when you write a 
behavior, you're really writing an Action file. Actions are HTML files. The BODY of 
an Action file generally contains an HTML form that accepts parameters for the 
action (for example, parameters indicating which layers are to be shown or 
hidden). The HEAD of an Action file contains JavaScript functions that process 
form input from the BODY and control the functions, arguments, and event 
handlers that are inserted into a users document. 
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How behaviors work 



When a user selects an HTML element in a Dreamweaver document and opens 
the Behaviors panel, the following chain of events occurs: 

1 The user clicks the Plus (+) button to display the Actions pop -up menu. 

2 Dreamweaver calls thecanAcceptBehaviorO function in each Action file to 
see whether this action is appropriate for the document or the selected element. 
If the return value of this function is false, Dreamweaver dims the action in 
the Actions pop-up menu. (For example, the Control Shockwave action is 
dimmed when the user's document has no Shockwave movies.) If the return 
value is a list of events, Dreamweaver compares each event with the valid 
events for the currently selected HTML element and target browser until it 
finds a match. 

3 Dreamweaver populates the Events pop-up menu with the matched event from 
canAcceptBehaviorO at the top of the list; if no match exists, the default 
event for the HTML element (marked in the Event file with an asterisk) 
becomes the top item. The remaining events in the menu are culled from the 
Event file. 

4 The user selects an action from the Actions pop-up menu. 

5 Dreamweaver calls the w i n d o w D i me n s i o n s ( ) function, if defined, to 
determine the size of the Parameters dialog box. If wi ndowDi men si ons ( ) is not 
defined, the size is determined automatically. 

6 Dreamweaver displays a dialog box containing the BODY elements of the Action 
file. If the Action files BODY tag contains an on Load handler, Dreamweaver 
executes it. 

7 The user fills in the parameters for the action. Dreamweaver executes event 
handlers associated with the form fields as the user encounters them. 

8 The user clicks OK. 

9 Dreamweaver calls the beha vi orFuncti on ( ) and appl yBehavi or ( ) functions 
in the selected Action file. These functions return strings that are inserted into 
the user's document. 

10 If the user later double-clicks the action in the Actions column, 
Dreamweaver reopens the Parameters dialog box, executing the on Load 
handler. Dreamweaver then calls the inspectBehaviorO function in 
the selected Action file, which fills in the fields with the data that the user 
entered previously. 
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Inserting multiple functions in the user's file 



Actions can insert multiple functions — the main behavior function plus any 
number of helper functions — into the HEAD. Two or more behaviors can even 
share helper functions, as long as the function definition is exactly the same in 
each Action file. One way of ensuring that shared functions are identical is to store 
each helper function in an external JavaScript file and insert it into the appropriate 
Action files using <SCRIPT S RC= " external Fi 1 e . j s " > . 

When the user deletes a behavior, Dreamweaver attempts to remove any unused 
helper functions associated with the behavior. If other behaviors are using a 
helper function, it will not be deleted. Because the algorithm for deleting helper 
functions errs on the side of caution, Dreamweaver may occasionally leave behind 
an unused function in the users document. 

What to do when an action requires a return value 

Sometimes an event handler must have a return value (for example, 
onMouseOver="wi ndow. status=' Thi s is a link'; return true"). But if 
Dreamweaver inserts "return behaviorName(args)" into the event handler, 
behaviors later in the list are skipped. 

To get around this limitation, set a variable called document.MM_returnValueto 
the desired return value within the string returned bybehaviorFunctionO. This 
setting causes Dreamweaver to insert return document . MM_returnVal ue at the 
end of the list of actions in the event handler. See the Validate Form.js file in the 
Configuration/ Behaviors/Actions folder within the Dreamweaver application 
folder for an example of the use of MM_returnVal ue. 

The behavior API 

Two behavior API functions are required (applyBehaviorO and 

be ha vi or Functi on ( )); the rest are optional. The functions in the behavior 

API differ from the functions in the main JavaScript API in three ways: 

• They are not methods of the d reamwea ver, dom, or si te object. 

• They are significant only in the context of Behavior files. That is, Dreamweaver 
automatically calls the applyBehaviorO function if it is defined in a Behavio r 
file, whereas a function named applyBehaviorO acts like a user-defined 
function in any other extension file — you have to call it explicitly. 

• You are responsible for writing the body of each function and returning a value, 
if required. This is the opposite of how the functions work in the main API: 
those you call and pass arguments to, and Dreamweaver generates return 
values, if any. Here Dreamweaver calls the functions and passes arguments to 
them, and you generate return values, if any. 
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applyBehavaorQ 



Description 

Inserts into the users document an event handler that calls the function inserted 
bybehaviorFunctionO. This function can also perform other edits on the user s 
document, but it must not delete the object to which the behavior is being applied 
or the object that receives the action. 

Arguments 

uniqueName 

The argument is a unique identifier among all instances of all behaviors in the 
user's document. Its format is functi on Name Integer, where fundi on Name is 
the name of the function inserted bybehaviorFunctionO. This argument is 
useful if you insert a tag into the user's document and you want to assign a unique 
value to its NAME attribute. 

Returns 

A string containing the function call to be inserted in the user's document, usually 
after accepting parameters from the user. IfapplyBehavior( ) determines that the 
user made an invalid entry, the function can return an error string instead of the 
function call. If the string is empty (return " " ; ), Dreamweaver reports no error; 
but if the string is non-empty and not a function call, Dreamweaver displays a 
dialog box with the text: In val i d input supplied for this behavior: 
[the string returned from appl yBehavi or ()]. If the return value is nul 1 
(return ;), Dreamweaver indicates that an error occurred but offers no specific 
information. 

Note: Quotation marks within the returned string must be preceded by a backslash (\) to 
avoid errors reported by the JavaScript interpreter. 
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Example 

The following instance ofapplyBehaviorO returns a call to the function 
MM_openBrWi ndow( ) and passes parameters given by the user (the height and 
width of the window; whether the window should have scroll bars, a toolbar, a 
location bar, and other features; and the URL that should open in the window): 

function appl yBehavi or( ) { 

van i ,theURL,theName,arrayIndex = 0; 

var argArray = new ArrayO; //use array to produce correct -> 
number of commas w/o spaces 

var checkBoxNames = new Array( "tool bar" , "1 ocati on" , "status" 
"menubar" , " scrol 1 ba rs " , " resi zabl e" ) ; 

for (i=0; KcheckBoxNames. length; { 

theCheckBox = eval ( "document . theForm . " + checkBoxNames [i ]) ; 
if (theCheckBox . checked ) a rgArray [a rray Index++] = -> 
(checkBoxNames[i ] + "=yes"); 

} 

i f (document . theForm. wi dth . val ue) 

argArray[arrayIndex++] = ("width=" + -< 

document . theForm . wi dth . val ue ) ; 
i f (document . theForm . hei ght . val ue ) 

argArray[arrayIndex++] = ("height=" + -> 

document . theForm. hei ght . val ue) ; 
theURL = escape(document . theForm. URL. val ue) ; 
theName = document . theForm . wi nName . val ue ; 
return "MM_openBrWi ndow( ' "+theURL+" ' , ' "+theName+" ' ,-< 
' H +argArray . joi n( )+" ' ) " ; 

} 
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behav§orFunctaon() 



Description 

Inserts one or more functions — surrounded by < SC R I PT 

LANGUAGE=" JavaScri pt "X/SCRI PT> tags, if none yet exist— into the HEAD of 
the users document. 

Arguments 

None. 

Returns 

Either a string containing the JavaScript functions to be inserted in the users 
document, or a string containing the names of the functions to be inserted into 
the users document. This value must be exactly the same every time (it cannot 
depend on input from the user). The functions are inserted only once, regardless 
of how many times the action is applied to elements in the document. 

Note: Quotation marks within the returned string must be preceded by a backslash (\) to 
avoid errors reported by the JavaScript interpreter. 

Example 

The following instance ofbehaviorFunctionO returns a function called 

MM_popupMsg( ): 

function behavi orFuncti on ( ) { 
return ""+ 

"function MM_popupMsg( theMsg) { //vl.0\n"+ 
" al ert(theMsg) ; \n"+ 
" I " ; 

} 

The following code would be equivalent to the preceding behavi orFuncti on () 
declaration, and is the method used to declare behavi orFuncti on ( ) in all 
behaviors shipped with Dreamweaver: 

function MM_popupMsg( theMsg ) { //vl.O 
al ert( theMsg) ; 

} 

function behavi orFuncti on () { 
return "MM_popupMsg" ; 

} 
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canAcceptBehaviorQ 



Description 

Determines whether the action is allowed for the selected HTML element and 
specifies the default event that should trigger the action. May also check for the 
existence of certain objects (such as Shockwave movies) in the user's document 
and disallow the action if these objects do not appear. 

Arguments 

HTM Lei ement 

The argument is the selected HTML element. 
Returns 

One of the following values: 

• true if the action is allowed but has no preferred events. 

• A list of preferred events (in descending order of preference) for this action. 
Specifying preferred events overrides the default event (as denoted with an 
asterisk in the Event file) for the selected object. See steps 2 and 3 in "How 
behaviors work" on page 88. 

• fa 1 s e if the action is not allowed. 

If canAcceptBehavi or( ) returns fal se, the action is dimmed in the Actions 
pop-up menu in the Behaviors panel. 

Example 

The following instance ofcanAcceptBehaviorO returns a list of p referred events 
for the behavior if the document has any named images: 

function canAcceptBehavi or () { 

var theDOM = dreamweaver . getDocumentDOM( ) ; 
// Get an array of all images in the document 
var alllmages = theDOM . get El ementsByTagName( ' IMG ') ; 
if (all Images . 1 ength > 0) { 

return "onMouseOver , onClick, onMouseDown " ; 
}el se{ 

return false; 

} 

} 
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displayHelpQ 



Description 

If this function is defined, a Help button appears below the OK and Cancel 
buttons in the Parameters dialog box. This function is called when the user 
clicks the Help button. 

Arguments 

None. 

Returns 

Nothing. 

Example 

The following instance ofdisplayHelpO opens, in a browser window, a file with 
instructions for using the behavior: 

function di spl ayHel p( ) { 

d rea mwea ver . browse Document ( ' http: //www. hotwi red . com/^ 
webmonkey/ j a vase ri pt/code_l i bra ry/wm_pos2_el mnt_dw/^ 
?tw=javascri pt ' ) ; 

} 

deleteBehavsorQ 

Description 

Undoes any edits performed byapplyBehaviorO. 

Note: Dreamweaver automatically deletes the function declaration and the event handler 
associated with a behavior when the user deletes the behavior in the Behaviors panel. 
Thus, it is necessary to define deleteBehavior() only if the appl yBehavi or ( ) function 
performed additional edits on the user's document (for example, if it inserted a tag). 

Arguments 

applyBehdviorString 

This argument is the string that was returned earlier by the a p p 1 y B e h a v i o r ( ) 
function. 

Returns 

Nothing. 
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identifyBehaviorArgumentsQ 

Description 

Identifies arguments from a behavior function call asnav,dep,URL, NS4 . Oref, 
I E4 .Oref, objName, or other so that URLs in behaviors can be updated if the 
user saves the document to another location, and so that the referenced files can 
be displayed in the site map and considered dependent files for the purposes of 
uploading to and downloading from a server. 

Arguments 

theFuncti onCa 1 1 

This argument is the string that was returned earlier by the a p p 1 y B e h a v i o r ( ) 
function. 

Returns 

A string containing a comma-separated list of the types of arguments in the 
function call. The length of the list must equal the number of arguments in the 
function call. Argument types are always one of the following: 

• nav specifies that the argument is a navigational URL and therefore that it 
should be displayed in the site map. 

• dep specifies that the argument is a dependent file URL and therefore that it 
should be included with all other dependent files when a document containing 
this behavior is downloaded from or uploaded to a server. 

• URL specifies that the argument is both a navigational URL and a dependent 
URL (or that it is a URL of unknown type), and therefore that it should be 
displayed in the site map and considered a dependent file when uploading to or 
downloading from a server. 

• NS4 .Oref specifies that the argument is a Navigator DOM object reference. 

• I E4 . 0 ref specifies that the argument is an Internet Explorer DOM 
object reference. 

• objName specifies that the argument is a simple object name, as specified in the 
NAME attribute for the object. This type was added in Dreamweaver 3. 

• other specifies that the argument is none of the above types. 
Example 

This simple example of identi fyBeha vi orArguments ( ) would work for the 
Open Browser Window behavior action, which returns a function that always has 
three arguments (the URL to open, the name of the new window, and the list of 
window properties): 

function identi fyBehavi orArguments( fnCal 1 Str) { 
return "URL, other , other" ; 

} 
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A more complex version of i denti fyBehavi orArguments ( ) is necessary for 
behavior functions that have a variable number of arguments (such as Show/ 
Hide Layer). For this version of i denti fyBehavi orArguments ( ), there is a 
minimum number of arguments, and additional arguments always come in 
multiples of the minimum number. In other words, a function with a minimum 
number of arguments of 4 may have 4, 8, or 12 arguments, but it will never have 
10 arguments. 

function i denti fyBehavi orArguments( fnCal 1 Str) { 
var 1 i stOf ArgTypes ; 

var itemArray = dreamweaver . getTokens ( f nCal 1 Str , '(),'); 

// The array of items returned by getTokensO includes the 
// function name, so the number of ^arguments* in the array is 
// the length of the array minus one. Divide by 4 to get the 
// number of groups of arguments, 
var numArgGroups = ( ( i temArray . 1 ength - l)/4); 

//For each group of arguments 
for (i=0; i < numArgGroups; i++){ 

// Add a comma and "NS4 . Oref , I E4 . Oref , other ,dep" (because this 

// hypothetical behavior function has a minimum of four 

// arguments: the Netscape object reference, the IE object 

// reference, a dependent URL, and perhaps a property value such 

// as "show" or "hide") to the existing list of argument types, 

// or if no list yet exists, add only 

// "NS4.0ref , I E4. Oref , other, dep" 

var 1 i stOf ArgTypes += (( 1 i stOf ArgTypes )?",":"" ) + 

"NS4.0ref, I E4. Oref , other, dep" ; 

} 
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mspectBehavsorQ 



Description 

Inspects the function call for a previously applied behavior in the user's document 
and sets the values of the options in the Parameters dialog box accordingly. If 
inspectBehaviorO is not defined, the default option values appear. 

Note: inspectBehaviorO must rely solely on information passed to it via the 
app lyBeha v iorString argument. Do not attempt to obtain other information about 
the user's document (for example, using dreamweaver . getDocumentDOM( )) within 
this function. 

Arguments 

app lyBehaviorString 

This argument is the string that was returned earlier by the a p p 1 y B e h a v i o r ( ) 
function. 

Returns 

Nothing. 

Example 

The following instance ofinspectBehaviorO, taken from Display Status 
Message.htm, fills in the Message field in the parameters form with the message 
that the user selected when the behavior was originally applied: 

f uncti on i nspectBehavi or(msgStr) { 

var startStr = msgStr . i ndexOf ( ) + 1; 

van endStr = msgStr . 1 ast IndexOf ( ); 

if (startStr > 0 && endStr > startStr) { 
document . theForm. message . val ue = -i 
unescQuotes ( msgStr . substri ng( sta rt St r , endStr ) ) ; 

} 



Note: For more information aboutthe unescQuotes ( ) function, seethe string.js file in the 
Configuration/Shared/MM/Scripts/CMN folder. 
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wmciowDsmenssonsO 

Description 

Sets specific dimensions for the Parameters dialog box. If this function is not 
defined, the window dimensions are computed automatically. 

Note: Do not define this function unless you want an Options dialog box larger than 
640x480 pixels. 

Arguments 

pi atform 

The value of the argument is either "maci ntosh " or " wi ndows ", depending on 
the users platform. 

Returns 

A string of the form "wi dth In Pixel s , hei ght In Pixel s". 

The returned dimensions are smaller than the size of the entire dialog box because 
they do not include the area for the OK and Cancel buttons. If the returned 
dimensions do not accommodate all options, scroll bars appear. 

Example 

The following instance of wi ndowDi men si ons ( ) sets the dimensions of the 
Parameters dialog box to 648 x 520 pixels: 

function wi ndowDi mensi ons ( ) { 
return "648,520"; 

} 



A sample behavior example 

To understand better how behaviors work and how you can create one, it's helpful 
to look at an example. The Configuration/Behaviors/Actions folder inside the 
Dreamweaver application folder contains many examples; however, most are likely 
to be too complex a starting point for all but the most advanced developers. The 
simplest Action file to start with is Call JavaScript.htm (along with its counterpart, 
Call JavaScript. js, which contains all the JavaScript functions). 

The following code presents a relatively simple example. It checks the brand of the 
browser and goes to one page if the brand is Netscape Navigator, and another if 
the brand is Microsoft Internet Explorer. This code could easily be expanded to 
check for other brands — such as Opera and WebTV — and modified to perform 
other actions besides going to URLs. 
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<html > 
<head> 

<ti tl e>behavi or "Check Browser Brand "</ti tl e> 

<meta http-equi v="Content-Type" content=" text/html "> 

<scri pt 1 anguage=" JavaScri pt"> 

// The function that will be inserted into the 
// HEAD of the user's document 

function checkBrowserBrand ( netscapeURL , expl orerURL) { 
if (navi gator . appName = "Netscape") { 

if (netscapeURL) 1 ocati on . href = netscapeURL; 
}else if (navi gator . appName == "Microsoft Internet Explorer") { 

if (expl orerURL) 1 ocati on . href = explorerURL; 

} 

} 

I j ******************* apj ********************** 

function canAcceptBehavi or ( ) { 
return true; 

} 

// Return the name of the function to be inserted into 
// the HEAD of the user's document 
function behavi orFuncti on ( ) { 
return "checkBrowserBrand"; 

} 

// Create the function call that will be inserted 
// with the event handler 
function appl yBehavi or ( ) { 

var nsURL = escape ( document . the Form. nsURL. val ue) ; 

var ieURL = escape( document . theForm. ieURL. val ue) ; 

if (nsURL && ieURL) { 

return "checkBrowserBrand ( \ ' " + nsURL + "\',V" + ieURL + -i 

}el se{ 

return "Please enter URLs in both fields." 

} 



// Extract the arguments from the function call 
// in the event handler and repopulate the 
// parameters form 
f uncti on i nspect Behavi or ( f nCal 1 ) { 

var argArray = getTokens ( f nCal 1 , "()',"); 

var nsURL = unescape( a rgArray [1] ) ; 

var ieURL = unescape( a rgArray [2] ) ; 

document .theForm. nsURL. val ue = nsURL; 

document. theForm. ieURL. val ue = ieURL; 

} 
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1 1 ***************** LOCAL FUNCTIONS ****************** 



II Put the cursor in the first text field 
// and select the contents, if any 
function 1 nitial izelll ( ) { 

document . the Form . nsURL . focus ( ) ; 

document.theForm.nsURL.select( ) ; 

} 

// Let the user browse to the Navigator and 
// IE URLs 

f uncti on browseForURLs(whi ch Button ) { 
var theURL = dreamwea ver . browseForFi 1 eURL( ) ; 
if (whichButton == "nsURL"){ 

document . theForm. nsURL. val ue = theURL; 
}el se{ 

document .theForm. ieURL. val ue = theURL; 

} 

} 

If*************** end OF JAVASCRIPT ***************** 

</scri pt> 

</head> 

<body> 

<form method="post" action="" name=" theForm") 

<table border="0 H eel 1 paddi ng="8"> 

<tr> 

<td nowrap="nowrap">&nbsp ; &nbsp ; Go to this URL if the browser is 
Netscape Navi gator : <br> 

<input type="text" name="nsURL" size="50" value="">   

<input type="button" name="nsBrowse" val ue="Browse . . . " -> 

onCl ick="browseForURLs( ' nsURL ' )"></td> 

</tr> 

<tr> 

<td nowrap="nowrap">&nbsp ; &nbsp ; Go to this URL is the browser is 
Microsoft Internet Expl orer : <br> 

<input type="text" name="ieURL" size="50" value="">   

<input type="button" name="i eBrowse" val ue="Browse . . . " 

onCl ick="browseForURLs( ' ieURL' )"></td> 

</tr> 

</table> 

</form> 

</body> 

</html> 
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CHAPTER 11 

The Fireworks Integration API 



FWLaunch is a C shared library that gives authors of objects, commands, 
behaviors, and Property inspectors the ability to communicate with Fireworks. 
This chapter describes the Fireworks integration API and how to use it; for general 
information on how C libraries interact with the JavaScript interpreter in 
Dreamweaver, see "C-Level Extensibility" on page 191. 

The Fireworks integration API 

All functions in the Fireworks integration API are methods of the FWLaunch 
object. Optional arguments are enclosed in braces ({ }). 

FWLaunch. hringDWToFrontQ 

Availability 

Dreamweaver 3.0, Fireworks 3.0 
Description 

Brings Dreamweaver to the front. 

Arguments 

None. 

Returns 

Nothing. 
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FWLaunch.bringFWToFrontO 

Availability 

Dreamweaver 3.0, Fireworks 3.0 
Description 

Brings Fireworks to the front if it is running. 

Arguments 

None. 

Returns 

Nothing. 

FWLaunch.execdsllnRrewGrksQ 

Availability 

Dreamweaver 3.0, Fireworks 3.0 
Description 

Passes the specified string of JavaScript to Fireworks for execution. 
Arguments 

javascri ptOrFi leURL 

The argument is either a string of literal JavaScript or the path to a .js or .jsf file, 
expressed as a file:// URL. 

Returns 

A cookie object if the JavaScript was passed successfully, or a nonzero error code 
indicating that one of the following errors occurred: 

• Invalid usage; j avascri ptOrFi 1 eURL was specified as nul 1 or empty string, 
or the path to the .js or .jsf file was invalid. 

• File I/O error; Fireworks is unable to create a Response file because the 
disk is full. 

• Error notifying Dreamweaver; the user is not running a valid version of 
Dreamweaver (3.0 or later). 

• Error launching Fireworks process; the function did not launch a valid version 
of Fireworks (3.0 or later). 

• User cancelled the operation. 
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FWLaunch.getJsResponseO 



Availability 

Dreamweaver 3.0, Fireworks 3.0 
Description 

Determines whether Fireworks is still executing the JavaScript passed to it by 
FWLaunch . execJsInFi reworks( ), whether the script completed successfully, or 
whether an error occurred. 

Arguments 

progressTrdckerCookie 

The argument is the cookie object returned by 

FWLaunch . execJsInFi reworks ( ). 

Returns 

A string containing the result of the script passed to 

FWLaunch . execJsInFi reworks( ) if the operation completed successfully, nul 1 
if Fireworks is still executing the JavaScript, or a nonzero error code indicating 
that one of the following errors occurred: 

• Invalid usage; a JavaScript error occurred as Fireworks was executing the script. 

• File I/O error; Fireworks is unable to create a Response file because the 
disk is full. 

• Error notifying Dreamweaver; the user is not running a valid version of 
Dreamweaver (3-0 or later). 

• Error launching Fireworks process; the function did not launch a valid version 
of Fireworks (3.0 or later). 

• User cancelled the operation. 
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Returns 

The following code passes the string "prompt (' PI ease enter your name:')" 
to FWLaunch .exec Js In Fi reworks ( ) and then checks for the result: 

var progressCooki e = FWLaunch . execJsInFi reworks( "promptC ' PI ease -> 
enter your name :')"); 
var doneFl ag = fal se ; 
while (!doneFlag){ 

// check for completion every 1/2 second 

setTimeout( ' check For Compl eti on( ) ' , 500) ; 

} 

f uncti on check For Compl eti on ( ) { 
if ( progressCooki e != null) { 

var response = FWLaunch . get JsResponse( progressCooki e ) ; 
i f ( response != nul 1 ) { 

if (typeof( response) == "number") { 

// error or user-cancel, time to close the window 
// and let the user know we got an error 
wi ndow. cl ose( ) ; 
alertC'An error occurred."); 
}el se{ 

// got a valid response! 

alertC'Nice to meet you, " + response); 

wi ndow. cl ose( ) ; 

} 

doneFlag = true; 

} 

} 

} 

FWLaunch, mayLaunchRreworksQ 

Availability 

Dreamweaver 2.0, Fireworks 2.0 
Description 

Determines whether it is possible to launch a Fireworks optimization session. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the platform is Windows or Macintosh. If 
Macintosh, indicates whether another Fireworks optimization session is not 
already running. 
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FWLaunch.optfmizeSnFireworksO 

Availability 

Dreamweaver 2.0, Fireworks 2.0 
Description 

Launches a Fireworks optimization session for the specified image. 
Arguments 

docURL, imageURL, {targetklidth}, (targetHei ghtj 

• The first argument is the path to the active document, expressed as a 
file:// URL. 

• The second argument is the path to the selected image. If the path is relative, it 
is relative to doc URL. 

• The third argument, if supplied, is the width to which the image should 
be resized. 

• The fourth argument, if supplied, is the height to which the image should 
be resized. 

Returns 

0 if a Fireworks optimization session is successfully launched for the specified 
image; otherwise, a nonzero error code indicating that one of the following 
errors occurred: 

• Invalid usage; docURL, imageURL, or both were specified as nul 1 or 
empty string. 

• File I/O error; Fireworks is unable to create a response file because the 
disk is full. 

• Error notifying Dreamweaver; the user is not running a valid version of 
Dreamweaver (2.0 or later). 

• Error launching Fireworks process; the function did not launch a valid version 
of Fireworks (2.0 or later). 

• User cancelled the operation. 
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FWLaunch.vaSfdateF[reworks() 

Availability 

Dreamweaver 2.0, Fireworks 2.0 
Description 

Looks for the specified version of Fireworks on the user's hard disk. 

Arguments 

{ vers ionNumber} 

The argument is a floating-point number greater than or equal to 2.0; it represents 
the version of Fireworks that should be searched for. If this argument is omitted, 
the default is 2 . 0. 

Returns 

A Boolean value indicating whether the specified version of Fireworks was found. 
Example 

The following code checks whether Fireworks 3.0 is installed: 

if ( FW Launch . val i date Fi reworks (3.0) ) { 

alert( "Fireworks 3.0 is installed."); 
}el se{ 

alert( "Fireworks 3.0 is not installed."); 

} 



A simple Fireworks integration example 

The following command asks Fireworks to prompt the user for his or her name, 
and then returns the name to Dreamweaver. 

<html> 
<head> 

<ti tl e>Prompt in Fi reworks</ti tl e> 

<meta http-equi v="Content-Type" content="text/html ; -> 

charset=iso-8859-l"> 

<scri pt> 

function commandButtons ( ) { 

return new Array (" Prompt" , "promptlnFi reworks( ) " , "Cancel", -< 
" readyToCancel ( ) " , "CI ose" , "wi ndow. cl ose( ) " ) ; 

} 



var gCancel Cl i eked = false; 

var gProgressTrackerCooki e = null; 

function readyToCancel ( ) { 
gCancel Cl i eked = true ; 

} 
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function promptlnFi reworks( ) { 

var i sFi reworks3 = FWLaunch . val i dateFi reworks ( 3 . 0 ) ; 
if ( ! i sFi reworks3) { 

alertC'You must have Fireworks 3.0 or later to use this -i 

command" ) ; 
return ; 



// Tell Fireworks to execute the promptO method. 
gProgressTrackerCooki e = FWLaunch . execJsInFi reworks^ 
( "prompt (' PI ease enter your name:')"); 

// null means it. wasn't launched, a number means an error code 
if (gProgressTrackerCooki e == null || -< 
typeof (gProgressTrackerCooki e) = "number") { 

wi ndow. cl ose( ) ; 

alertCan error occurred"); 

gProgressTrackerCooki e = null; 
} else { 

// bring Fireworks to the front 
FWLaunch . bri ngFWToFront( ) ; 

// start the checking to see if Fireworks is done yet 
checkOneMoreTime( ) ; 

} 

} 

function checkOneMoreTi me( ) { 

// Call checkJsResponse( ) every 1/2 second to see if Fireworks 
// is done yet 

wi ndow. setTimeout( "checkJs Response ( ) ; " , 500) ; 



function checkJsResponse( ) { 
va r response = null; 

// The user clicked the cancel button, close the window 
if (gCancelClicked) { 

wi ndow. cl ose( ) ; 

al ert( "cancel clicked"); 
} else { 

// We're still going, ask Fireworks how it's doing 
if (gProgressTrackerCooki e != null) 
response = -< 

FWLaunch.getJsResponse(gProgressTrackerCookie); 

i f ( response == nul 1 ) { 

// still waiting for a response, call us again in 1/2 a 
// second 

checkOneMoreTime( ) ; 
} else if (typeof ( response) == "number") { 

// if the response was a number, it means an error 
// occurred 
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// the user cancelled in Fireworks 

wi ndow. cl ose( ) ; 

alertCan error occurred."); 



} else { 

// got a valid response! This return value might not 

// always be a useful one, since not all functions in 

// Fireworks return a string, but we know this one does, 

// so we can show the user what we got. 

wi ndow. cl ose( ) ; 

FW Launch . bri ngDWTo Front ( ) ; 

// bring Dreamweaver to the front 

alert ("Nice to meet you, " + response + "!"); 

} 

} 

} 

</scri pt> 
</head> 
<body> 
<form> 

<table wi dth=" 313 " nowrap> 
<tr> 

<td>This command asks Fireworks to execute the promptO 

function. When you click Prompt, Fireworks comes forward and 

asks you to enter a value into a dialog box. That value is then 

returned to Dreamweaver and displayed in an alert. </td> 

</tr> 

</table> 

</form> 

</body> 

</html> 
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CHAPTER 12 

The Flash Objects API 



The Flash objects API is an extension to the Objects API that allows extension 
developers to build objects that create simple Flash content. This API provides a 
way to set parameters in a Flash Generator template (.swt file) and output a Flash 
Movie or Image file. The API allows you to create new Flash objects as well as read 
and manipulate existing Flash objects. The Flash button and Flash text features are 
built using this API. 

The .swt file is a Flash Generator Template file, which contains all the necessary 
information required to construct a Flash Object file (.swf). These API functions 
allow you to create a new .swf file (or Image file) from a .swt file by replacing the 
parameters of the .swt file with real values. For more information on Flash and 
Flash Generator, see their respective manuals. 
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SWFFile.createRieQ 



Description 

Generates a new Flash Object file with the specified template and array of 
parameters. Also creates a GIF, PNG, JPEG, and MOV version of the title if 
file names for those formats are specified. 

If you want to specify an optional parameter that comes after optional parameters 
you do not want to specify, you need to specify empty strings for the parameters 
you don't want to specify. For example, if you want to specify a .png file, but not a 
.gif file, you'd need to specify an empty string before specifying the .png file name. 

Arguments 

tempi ateFil e, tempi ateParams, swf Fil eName, {gi fFi 1 eName}, 
{pngFi 1 eName}, {jpgFi 1 eName}, {movFi 1 eName}, {generatorParams} 

• temp 1 a teFi 1 e is a path to a Template file, expressed as a f i 1 e : / / URL. This 
file can be a .swt file. 

• tempi ateParams is an array of name/value pairs where the names are the 
names of the parameters in the .swt file and the values are what you want to set 
those parameters to be. For an .swf file to be recognized by Dreamweaver as a 
Flash object, the first parameter must be " dwType " . Its value should be a string 
representing the name of the object type, such as "Flash Tex t " . 

• swfFi 1 eName is the output file name of an .swf file name, expressed as a 
file:// URL, or an empty string to ignore. 

• {gifFil eName } is the output file name of a .gif file name, expressed as a 
file:// URL. Optional. 

• { pngFi 1 eName] is the output file name of a .png file name, expressed as a 
file:// URL. Optional. 

• { JpgFi 1 eName } is the output file name of a .jpeg file name, expressed as a 
file:// URL. Optional. 

• { mo vF / 1 eName} is the output file name of a QuickTime movie file name, 
expressed asafile:// URL. Optional. 

• {generatorParams} is an array of strings representing optional Generator 
command line flags. Optional. Each flag must be followed in the array by its 
data items. Some commonly used flags are listed in the following table. 



Option Flag 


Data 


Description 


Example 


-defaultsize 


width, height 


Sets the output image size to 


" -defaul tsi ze" , 






the specified width and height. 


"640", "480" 


-exact Fit 


none 


Stretches the contents in the 


" -exactFi t " 






output image to fit exactly into 








the specified output size. 
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Returns 

A string containing one of the following values: 

• " n o E r r o r " means the call completed successfully. 

• " i n v a 1 i d Temp 1 a t e F i 1 e " means the specified Template file was invalid or 
not found. 

• " i n v a 1 i d 0 u t p u t F i 1 e " means at least one of the specified output file names 
was invalid. 

• " i nval i dData " means that one or more of the temp 1 a teParams was invalid. 

• "ini tGeneratorFai 1 ed" means Generator could not be initialized. 

• " outOf Memory " means insufficient memory to complete the operation. 

• "unknownError" means an unknown error occurred. 
Example 

The following JavaScript creates a Flash Object file of type "my Type " that replaces 
any occurrence of " text " inside the Template file with "Hello World". It will 
create a .gif file as well as an .swf file. 

var params = new Array; 
params[0] = "dwType" ; 
params[l] = "my Type" ; 
params[2] = "text" ; 
params[3] = "Hello World"; 

errorString - SWFFi 1 e . createFi 1 e( "fi 1 e: ///MyMac/test . swt" , -< 
params , "fi 1 e : ///MyMac/test . swf " , "fi 1 e : ///MyMac/test . gi f " ) ; 

SWFFile.getNaturaSSszeQ 

Description 

Returns the natural size of any Flash movie. 

Arguments 

fi leName 

fi 1 eName is a path to the Flash movie, expressed as a f i 1 e : / / URL. 
Returns 

An array containing two elements, representing the width and the height of the 
movie, or nul 1 if the file is not a Flash file. 
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SWFFile.getObjectTypeO 

Description 

Returns the Flash object type — the value that was passed in the dwTy pe parameter 
when the file was created by the SW FFi 1 e . c rea te Fi 1 e ( ) function. 

Arguments 

fileName 

fi 1 eName is a path to a Flash Object file, expressed asafile:// URL. This file is 
usually an .swf file. 

Returns 

A string representing the object type, or n u 1 1 if the file is not a Flash Object file or 
if the file could not be found. 

Example 

The following code checks to see if the file, test.swf, is a Flash object of type 

myType: 

if ( SWFFi 1 e . getObjectType( "f i 1 e : ///MyMac/test . swf " ) == "myType" 
){ 

alert ("This is a myType object."); 
}el se{ 

alert ("This is not a myType object."); 

} 
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SWFFile.readFne() 



Description 

Reads a Flash Object file. 

Arguments 

fi leName 

fi 1 eName is a path to a Flash Object file to read, expressed as a f i 1 e : / / URL. 
Returns 

An array of strings. The first array element is the full path to the template .swt file. 
The following strings represent the parameters (name/value pairs) for the object. 
Each name is followed in the array by its value. The first name/value pair is 
" dwTy pe " followed by its value; null is returned if the file cannot be found or if it 
is not a Flash Object file. 

Example 

Calling this: 

var params = SWFFi 1 e . readFi 1 e( " f i 1 e : // /My Mac/ test . swf " ) ; 
will return the following in the parameters array: 

"fi 1 e: ///MyMac/test . swt" // the template file used to create this 
.swf file 

"dwType" // first parameter 

"my Type" // first parameter value 

"text" // second parameter 

"Hello World" // second parameter value 



The Flash Objects API 113 



114 Chapter 12 




CHAPTER 13 

The Design Notes AP 



UltraDev 4, Dreamweaver 4. and Fireworks 4 offer a way for Web designers and 
developers to store and retrieve extra information about documents — information 
such as review comments, change notes, or the source file for a GIF or JPEG — in 
files called Design Notes. 

MMNotes is a C shared library that lets extensions authors read and write Design 
Notes files. Like the DWfile snared library, MMNotes has a JavaScript API that 
makes it possible to call the functions contained in the library from objects, 
commands, behaviors, floating panels, Property inspectors, and data translators. 

MMNotes also has a C API that gives other applications an opportunity to read 
and write Design Notes files. The MMNotes shared library can be used 
independently of Dreamweaver, even if Dreamweaver is not installed. 

For more information about using the Design Notes feature from within 
Dreamweaver, see Using Dreamweaver. 
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How Design Notes work 



Each Design Notes file stores information for a single document. If one or more 
documents in a folder has a Design Notes file associated with it, Dreamweaver 
creates a _notes subfolder where Design Notes files can be stored. The _notes 
folder and the Design Notes files it contains are not visible in the Site window, but 
they show up in the Finder or Windows Explorer. A Design Notes file name is 
made up of the main file name plus the extension .mno. For example, the Design 
Notes file associated with avocado8.gif is avocado8.gif.mno. 

Design Notes files are XML files that store information in a series of key/value 
pairs. The key describes the type of information that is being stored, and the value 
represents the information itself. Keys are limited to 64 characters. 

The Design Notes file for foghorn.gif might look like this: 

<?xml versi on="l . 0" encodi ng=" i so-8859- 1 " ?> 
<info> 

<infoitem key=" FW_source" val ue="f i 1 e : ///C | si tes/-> 
dreamcentral / i ma ges/sourceFi 1 es/ foghorn . png" /> 
<infoitem key="Author " value="Heidi B." /> 
<infoitem key="Status" val ue=" Fi nal draft, approved by ^ 
Jay L." /> 
</info> 

The Design Notes JavaScript API 

All functions in the Design Notes JavaScript API are methods of the MMNotes 
object. Optional arguments are enclosed in braces ({ }). 

MMNotes.cIoseC) 

Description 

Closes the specified Design Notes file and saves any changes. If all key/ value pairs 
were removed, Dreamweaver deletes the Design Notes file. 

Arguments 

fi leHandle 

The argument is the file handle returned by MMNotes. open ( ). 

Returns 

Nothing. 

Example 

See "MMNotes.setQ" on page 120. 
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MMNotesiilePathToLocalURL() 

Description 

Converts the specified local drive path to a file:// URL. 

Arguments 

dri vePath 

The argument is a string containing the full drive path. 
Returns 

A string containing the file:// URL for the specified file. 
Example 

A call to MMNotes.fi 1 e Pat hTo Local URL ( ' C : /si tes/webdev/i ndex . htm' ) 
returns "fi 1 e: 1 1 ic | si tes/webdev/i ndex . htm". 

MMNotes.getQ 

Description 

Gets the value of the specified key in the specified Design Notes file. 

Arguments 

fi leHandle, key Name 

• The first argument is the file handle returned byMMNotes.openO. 

• The second argument is a string containing the name of the key. 
Returns 

A string containing the value of the key. 
Example 

See "MMNotes.getKeysO" on page 118. 

MMNotes 0 getKeyCount() 

Description 

Gets the number of key/value pairs in the specified Design Notes file. 

Arguments 

fi leHandle 

The argument is the file handle returned byMMNotes.openO. 
Returns 

An integer representing the number of key/value pairs in the Design Notes file. 
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MMNotes,getKeys() 



Description 

Gets a list of all the keys in a Design Notes file. 

Arguments 

fi leHandle 

The argument is the file handle returned byMMNotes.openO. 
Returns 

An array of strings, each containing the name of a key. 
Example 

The following code might be used in a custom floating panel to display the 
Design Notes information for the active document: 

var noteHandle = MMNotes . open ( dw . get Document DOM ( ) . URL) ; 

var theKeys = MMNotes . getKeys ( noteHandl e ) ; 

var noteStri ng = " " ; 

var theVal ue = " " ; 

for (var 1=0; i < theKeys . 1 ength ; 

theValue = MMNotes . get ( noteHandl e , theKeys [i ]) ; 

noteString += theKeys[i] + " = " theValue + "\n"; 

} 

document . theForm. bi gTextFi el d . val ue = noteString; 



MyNofes,getSsteRoofForFne{) 

Description 

Determines the site root for the specified Design Notes file. 

Arguments 

fileURL 

The argument is the path to a local file, expressed as a file:// URL. 
Returns 

A string containing the path of the Local Root folder for the site, expressed as 
a file:// URL, or an empty string if Dreamweaver (or UltraDev) is not installed 
or the Design Notes file is outside of any site defined with Dreamweaver 
or UltraDev. 
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MMNotes.getVersionMameC) 

Description 

Gets the version name of the MMNotes shared library, which indicates the 
application that implemented it. 

Arguments 

None. 

Returns 

A string containing the name of the application that implemented the MMNotes 
shared library. 

Example 

Calling MMNotes. getVersionNa me () from a Dreamweaver command, object, 
behavior, Property inspector, floating panel, or data translator returns 
"Dreamweaver". Calling MMNotes . getVersi onName( ) from Fireworks also 
returns "Dreamweaver" because Fireworks uses the same version of the library 
(the one created by the Dreamweaver engineering team). 

MyNotes.getVersionNumO 

Description 

Gets the version number of the MMNotes shared library. 

Arguments 

None. 

Returns 

A string containing the version number. 

MMNotesJocalURLToFnePathO 

Description 

Converts the specified file:// URL to a local drive path. 

Arguments 

fileURL 

The argument is the path to a local file, expressed as a file:// URL. 
Returns 

A string containing the local drive path for the specified file. 
Example 

A call to MMNotes. 1 oca 1 URLToFi 1 ePath ( * f i 1 e : ///Maci ntoshHD/i mages/ 
moon . gif ' ) returns "Maci ntoshHD : images :moon . gi f ". 
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MMNotes,open{) 

Description 

Opens the Design Notes file associated with the specified file, or creates one if 
none exists. 

Arguments 

filePath, {bForceCreate'j 

• The first argument is the path to the main file with which the Design Notes file 
is associated, expressed as a file:// URL. 

• The second argument is a Boolean value indicating whether to create the 
Note even if Design Notes is turned off for the site or if fi 1 ePa th is not 
associated with any site. 

Returns 

The file handle for the Design Notes file, or zero (0) if the file was not opened 
or created. 

Example 

See "MMNotes.set()" on page 120. 

MMNotes B remove() 

Description 

Removes the specified key (and its value) from the specified Design Notes file. 

Arguments 

fi leHandle, key Name 

• The first argument is the file handle returned byMMNotes.openO. 

• The second argument is a string containing the name of the key to be removed. 
Returns 

A Boolean value indicating whether the operation was successful. 

MMNotes c set{) 

Description 

Creates or updates one key/value pair in a Design Notes file. 
Arguments 

fi 1 eHandl e, keyName, val ueStri ng 

• The first argument is the file handle returned byMMNotes.openO. 

• The second argument is a string containing the name of the key. 

• The third argument is a string containing the value. 
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Returns 

A Boolean value indicating whether the operation was successful. 
Example 

The following code opens the Design Notes file associated with a file in the 
dreamcentral site called peakhike99/index.html, adds a new key/value pair, 
changes the value of an existing key, and then closes the Note file. 

var noteHandle = MMNotes . open( ' f i 1 e : ///c | si tes/dreamcentral /-> 
peak hi k e 9 9 / i ndex . html ' , true) ; 

MMNotes. set(noteHandle, "Author" ,"M. G. Miller"); 
MMNotes. set(noteHandle, "Last Changed ", "August 28, 1999"); 
MMNotes.close(noteHandle); 

The Design Notes C API 

In addition to the JavaScript API, the MMNotes shared library also exposes a 
C API that lets other applications create Design Notes files. It is not necessary 
to call these C functions directly if you are using the MMNotes shared library 
in Dreamweaver; the JavaScript versions of the functions call them for you. 

This section contains descriptions of the functions, their arguments, and 
their return values; you can find definitions for the functions and data types 
in the MMInfo.h file in the Extending/c_files folder inside the Dreamweaver 
application folder. 

Optional arguments are enclosed in braces ({ }). 

void CloseNotesFHeQ 

Description 

Closes the specified Design Notes file and saves any changes. If all key/value pairs 
were removed from the Note, Dreamweaver deletes it. 

Arguments 

FileHandle noteHandle 

The argument is the file handle returned byOpenNotesFileO. 

Returns 

Nothing. 
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BOOL Fi!ePathToLocaSURL() 

Description 

Converts the specified local drive path to a file:// URL. 
Arguments 

const char* dri vePath, char* 7 ocal URLBuf, int 1 ocal URLMaxLen 

• The first argument is a string containing the full drive path. 

• The second argument is the buffer where the file:// URL should be stored. 

• The third argument is the maximum size of / oca 1 URLBuf. 
Returns 

A Boolean value indicating whether the operation was successful; stores the 
file:// URL in local URLBuf. 

BOOL 6etNote() 

Description 

Gets the value of the specified key in the specified Design Notes file. 
Arguments 

FileHandle noteHandl e, const char keyName[64], char* valueBuf, int 
val ueBuf Length 

• The first argument is the file handle returned byOpenNotesFileO. 

• The second argument is a string containing the name of the key. 

• The third argument is the buffer where the value should be stored. 

• The fourth argument is the integer returned by 

GetNotel_ength( noteHand le, keyName), indicating the maximum length of 
the value buffer. 

Returns 

A Boolean value indicating whether the operation was successful; stores the value 
ofthekeyin valueBuf. 

Example 

The following code gets the value of the comments key in the Design Notes file 
associated with welcome.html: 

FileHandle noteHandle = OpenNotesFi 1 e( " f i 1 e : ///c | si tes/avocado8/^ 
i wjs/wel come . html " ) ; 

int valueLength = GetNotesLength ( noteHandle, "comments"); 
char* valueBuffer = new char[val ueLength + 1] 
GetNote(noteHandl e , "comments", valueBuffer, valueLength + 1); 
pri ntf ( "Comments : %s",valueBuffer); 
CI oseNotesFi 1 e( noteHandl e ) ; 
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int GetNoteLengthQ 

Description 

Gets the length of the value associated with the specified key. 
Arguments 

Fi 1 eHandl e noteHandle, const char keyName[64] 

• The first argument is the file handle returned byOpenNotesFileO. 

• The second argument is a string containing the name of the key. 
Returns 

An integer representing the length of the value. 
Example 

See "BOOL GetNoteQ" on page 122. 

int GetNotesKeyCount() 

Description 

Gets the number of key/value pairs in the specified Design Notes file. 
Arguments 

Fi 1 eHandl e noteHandle 

The argument is the file handle returned byOpenNotesFileO. 
Returns 

An integer representing the number of key/value pairs in the Design Notes file. 
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BOOL GetNotesKeysQ 

Description 

Gets a list of all the keys in a Design Notes file. 
Arguments 

FileHandle noteHandl e, char* keyBuf Array [64], int keyArrayMaxLen 

• The first argument is the file handle returned byOpenNotesFileO. 

• The second argument is the buffer array where the keys should be stored. 

• The third argument is the integer returned byGetNotesKeyCount(/70te//a/7(//e), 
indicating the maximum number of items in the key buffer array. 

Returns 

A Boolean value indicating whether the operation was successful; stores the key 
names in key But Array. 

Example 

The following code prints the key names and values of all the keys in the Design 
Notes file associated with welcome.html: 

typedef char[64] InfoKey; 

FileHandle noteHandle = OpenNotesFi 1 e( " f i 1 e : ///c | si tes/avocado-8/^ 
i wjs/wel come . html " ) ; 
if (noteHandle > 0){ 

int keyCount = GetNotesKeyCount ( noteHandl e ) ; 

if (keyCount <= 0) 
return ; 

InfoKey* keys = new InfoKey [ keyCount] ; 

BOOL succeeded = GetNotesKeys ( noteHandl e , keys, keyCount); 

if (succeeded)! 

for (int i=0; i < keyCount; i++){ 
printfCKey is: %s\n", keys[i]); 

pri ntf ( "Val ue is: %s\n\n", GetNote( noteHandl e , keys[i]); 

} 

delete keys; 

} 

CI oseNotesFi 1 e( noteHandl e ) ; 
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BOOL GetSiteRootForRleQ 

Description 

Determines the site root for the specified Design Notes file. 
Arguments 

char* filePath, char* si teRootBuf, i nt si teRootBufMaxLen , {InfoPrefs* 
infoPrefs] 

• The first argument is the file handle returned byOpenNotesFileO. 

• The second argument is the buffer where the site root should be stored. 

• The third argument is the maximum size of s / teRootBuf. 

• The fourth argument is a reference toastructin which the preferences for the 
site should be stored. 

Returns 

A Boolean value indicating whether the operation was successful; stores the site 
root in si teRootBuf. If infoPrefs is specified, the function also returns the 
Design Notes preferences for the site. The I nf oPref s struct has two variables: 

bUseDesign Notes and bUpl oadDe si gn Notes, both of type BOOL. 

BOOL 6etVersionNafne() 

Description 

Gets the version name of the MMNotes shared library, which indicates the 
application that implemented it. 

Arguments 

char* versi onNameBuf, i nt versi onNameBufMaxLen 

• The first argument is the buffer where the version name should be stored. 

• The second argument is the maximum size of vers i onNameBuf. 
Returns 

A Boolean value indicating whether the operation was successful; stores the 
version name in versi onNameBuf. 
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BOOL GetVersionNumQ 

Description 

Gets the version number of the MMNotes shared library. 
Arguments 

char* versi onNumBuf, int versi onNumBufMaxLen 

• The first argument is the buffer where the version number should be stored. 

• The second argument is the maximum size of vers ionNumBuf. 
Returns 

A Boolean value indicating whether the operation was successful; stores the 
version number in vers ionNumBuf. 

BOOL LocaSURLToFnePathQ 

Description 

Converts the specified file:// URL to a local drive path. 
Arguments 

const char* 7 ocal URL, char* dri vePathBuf, int dri vePathMaxLen 

• The first argument is the path to a local file, expressed as a file:// URL. 

• The second argument is the buffer where the local drive path should be stored. 

• The third argument is the maximum size of dri vePathBuf. 
Returns 

A Boolean value indicating whether the operation was successful; stores the local 
drive path in dri vePathBuf . 

FaleHandle OpenNotesFileQ 

Description 

Opens the Design Notes file associated with the specified file, or creates one if 
none exists. 

Arguments 

const char* 1 oca 1 Fi 1 eURL , {BOOL bForceCreate] 

• The first argument is a string containing the path to the main file with which 
the Design Notes file is associated, expressed as a file:// URL. 

• The second argument is a Boolean value indicating whether to create the 
Design Notes file even if Design Notes is turned off for the site or if filePath 
is not associated with any site. 
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FileHandle OpenNotesFHewithOpenRagsO 

Description 

Opens the Design Notes file associated with the specified file, or creates one if 
none yet exists. You can open the file in read-only mode. 

Arguments 

const char* local FileURL, {BOOL bForceCreate} , {BOOL bReadOnly] 

• The first argument is a string containing the path to the main file with which 
the Design Notes file is associated, expressed as a file:// URL. 

• The second argument is a Boolean value indicating whether to create the 
Design Notes file even if Design Notes are turned off for the site or filePathis 
not associated with any site. The default value is f a 1 se. This argument is 
optional, though you need to specify it if you specify the third argument. 

• The third argument is a Boolean value indicating whether to open the file in 
read-only mode. The default value is f a 1 se. This argument is optional. 

BOOL RemoveNoteQ 

Description 

Removes the specified key (and its value) from the specified Design Notes file. 
Arguments 

FileHandle noteHandl e, const char keyName[64] 

• The first argument is the file handle returned byOpenNotesFileO. 

• The second argument is a string containing the name of the key to be removed. 
Returns 

A Boolean value indicating whether the operation was successful. 

BOOL SetNote() 

Description 

Creates or updates one key/value pair in a Design Notes file. 
Arguments 

FileHandle noteHandle, const char keyName[64], const char* value 

• The first argument is the file handle returned byOpenNotesFileO. 

• The second argument is a string containing the name of the key. 

• The third argument is a string containing the value. 
Returns 

A Boolean value indicating whether the operation was successful. 
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CHAPTER 14 

The File I/O API 



Dreamweaver includes a C shared library called DWfile that gives authors of 
objects, commands, behaviors, data translators, floating panels, and Property 
inspectors the ability to read and write files on the local file system. This chapter 
describes the file I/O API and how to use it. 

For general information on how C libraries interact with the JavaScript interpreter 
in Dreamweaver, see "C-Level Extensibility" on page 191. 

Verifying that DWfile Is installed 

To access the functions in the DWfile library, the library must be present in the 
Co nfiguration/JS Extensions folder and loaded by Dreamweaver. Because DWfile 
did not ship with Dreamweaver 2 (it was available as a separate download that the 
user had to install), you should verify that the library is available before calling any 
of its functions. You can do this by checking the typeof ( DWf i 1 e ) . If DWfile does 
not exist, typeof(DWfile) returns undefined. For example, if you are using 
DWfile in the context of a command, you might check for the existence of 
DWfile as part of the can Accept Command ( ) function: 

// Returns true if typeof ( DWf i 1 e ) is not undefined, false otherwise, 
function canAcceptCommand ( ) { 

return ( typeof ( DWf i 1 e ) != "undefined"); 

} 
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The fife I/O API 



All functions in the file I/O API are methods of the DWf i 1 e object. Optional 
arguments are enclosed in braces ({ }). Functions with an availability of 2.0 
were included in the version of DWfile that was supplied as a download for 
Dreamweaver 2 from the Macromedia Web site. This version of DWfile may 
have been installed with third-party objects. 

DWfile.copyQ 

Availability 

Dreamweaver 3.0 

Description 

Copies the specified file to the specified URL. 
Arguments 

original URL, copyURL 

• The first argument is the file you want to copy, expressed as a file:// URL. 

• The second argument is the location where you save the copied file, expressed 
as a file:// URL. 

Returns 

true if the copy succeeded, f al se otherwise. 
Example 

The following code copies a file called myconfig.cfg to myconfig_backup.cfg.: 

var fileURL = "f i 1 e : ///c | /Conf i g/myconf i g . cfg" ; 

var newURL ="fi 1 e : life | /Conf i g/myconf i g_backup . cfg" ; 

DWfile. copy(fileURL, newURL); 

OWfilexreateFoiderQ 

Availability 

Dreamweaver 2.0 

Description 

Creates a folder (directory) at the specified location. 

Arguments 

folderURL 

The argument is the location of the folder you want to create, expressed as a 
file:// URL. 

Returns 

true if the folder was successfully created, f a 1 se otherwise. 
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Example 

The following code attempts to create a folder called tempFolder at the top 
level of the C drive and displays an alert box indicating whether the operation 
was successful. 

var folderURL = "f i 1 e : ///c | /tempFol der" ; 
if (DWfile.createFolder(folderURL)){ 

alertCCreated " + folderURL); 
}el se{ 

alertCUnable to create " + folderURL); 

} 



DWfiSe,exasts() 

Availability 

Dreamweaver 2.0 

Description 

Tests for the existence of the specified file. 

Arguments 

fileURL 

The argument is the file you are looking for, expressed as a file:// URL. 
Returns 

true if the file exists, f al se otherwise. 
Example 

The following code checks for a file called mydata.txt and displays an alert box 
that tells the user whether the file exists. 

var fileURL = "f i 1 e : ///c | /temp/mydata . txt" ; 
if (DWfile.exists(fileURL)H 

alert( fileURL + " exists!"); 
}else{ 

alert( fileURL + " does not exist."); 

} 
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DWfiSe.getAttributesQ 

Availability 

Dreamweaver 2.0 

Description 

Gets the attributes of the specified file or folder. 

Arguments 

fileURL 

The argument is the file or folder for which you want to get attributes, expressed 
as a file:// URL. 

Returns 

A string representing the attributes of the specified file or folder, or nul 1 if the file 
or folder does not exist. Characters in the string represent the attributes as follows: 

• R is read only. 

• D is folder (directory). 

• H is hidden. 

• S is system file or folder. 
Example 

The following code gets the attributes of the file mydata.txt and displays an alert 
box if the file is read only: 

var URL = "f i 1 e : ///c | /temp/mydata . txt" ; 
var str = DWf i 1 e . getAttri butes(URL) ; 
if (str && (str.indexOfCR") != -1)){ 
alerKURL + " is read only!"); 

} 
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DWfiSe,getModsf[catsonDate() 

Availability 

Dreamweaver 2.0 

Description 

Gets the time when the file was last modified. 

Arguments 

fileURL 

The argument is the file for which you are checking the last modified time, 
expressed as a file:// URL. 

Returns 

A string containing a hexadecimal number that represents the number of time 
units that have elapsed since some base time. The exact meaning of time units and 
base time is platform-dependent; in Windows, for example, a time unit is 100ns, 
and the base time is January 1st, 1600. 

Example 

Its most useful to call the function twice and compare the return values 
because the value returned by this function is platform-dependent and is 
not a recognizable date and time. For example, the following code gets the 
modification dates of filel.txt and file2.txt and displays an alert box 
indicating which file is newer: 

var filel = "file:///c| /temp/fi 1 el .txt" ; 
var file2 = "f i 1 e : Ilic j /temp/fi 1 e2 . txt" ; 
var timel = DWf i 1 e . getModi f i cati onDate( f i 1 el ) ; 
var time2 = DWf i 1 e . getModi fi cati onDate( fi 1 e2 ) ; 
if (timel == time2){ 

alert( "filel and file2 were saved at the same time"); 
}else if (timel < time2){ 

alertCfilel older that file2 M ); 
}else{ 

alertCfilel is newer than f i 1 e 2 " ) ; 

} 



The File I/O API 133 



DWfiSe,getCreataonDate() 



Availability 

Dreamweaver 4.0 

Description 

Gets the time when the file was created. 

Arguments 

fileURL 

The argument is the file for which you are checking the creation time, expressed as 
a file:// URL. 

Returns 

A string containing a hexadecimal number that represents the number of time 
units that have elapsed since some base time. The exact meaning of time units and 
base time is platform-dependent; in Windows, for example, a time unit is 100ns, 
and the base time is January 1st, 1600. 

Example 

You can call this function and the DWfi 1 e . getModi fi cati onDate( ) function on 
a file to compare the modification date to the creation date: 

var filel = "file:///c| /temp/f i 1 el . txt" ; 
var timel = DWf i 1 e . getCreati onDate( f i 1 el ) ; 
var time2 = DWf i 1 e . getModi fi cati onDate( fi 1 el ) ; 
if (timel == time2){ 

alertC'filel has not been modified since it was created"); 
}else if (timel < time2){ 

alertC'filel was last modified on time2"); 

} 

DWfileJistFoWerQ 

Availability 

Dreamweaver 2.0 

Description 

Gets a list of the contents of the specified folder. 
Arguments 

folderURL, {constraint} 

• The first argument is the folder for which you want a contents list, expressed 
as a file:// URL, plus an optional wildcard file mask. Valid wildcards are * 
(matches 1 or more characters) and ? (matches a single character). 

• The second argument, if supplied, must be either "files" (return only files) or 
"directories" (return only directories). If omitted, the function returns both 
files and directories. 
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Returns 

An array of strings representing the contents of the folder. 
Example 

The following code gets a list of all the text (.txt) files in the temp folder and 
displays the list in an alert box: 

var folderURL = "f i 1 e : ///c | /temp" ; 
var fi 1 eMask = "*. txt" ; 

var list = 1 i stFol derCfol derURL + ■/" + f i 1 eMask , "files"); 
if (list){ 

al ert( fol derURL + " contains: " + 1 i st . joi n ( " \n " ) ) ; 

} 

OWfHe.readQ 

Availability 

Dreamweaver 2.0 

Description 

Reads the contents of the specified file into a string. 

Arguments 

fileURL 

The argument is the file you want to read, expressed as a file:// URL. 
Returns 

A string containing the contents of the file, or n ul 1 if the read fails. 
Example 

The following code reads the file mydata.txt and, if successful, displays an alert 
box with the contents of the file: 

var fileURL = "fi 1 e: ///c | /temp/mydata . txt" ; 
var str = DWfile.read( fileURL); 
if (str){ 

alert( fileURL + " contains: " + str); 

} 
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DWfi!e,remove() 

Availability 

Dreamweaver 3.0 

Description 

Moves the specified file to the Recycling Bin or Trash. 

Arguments 

fileURL 

The argument is the file you want to remove, expressed as a file:// URL. 
Returns 

true if the operation succeeded, fal se otherwise. 

DWfiSe.writeQ 

Availability 

Dreamweaver 2.0 

Description 

Writes the specified string to the specified file. If the specified file does not yet 
exist, it is created. 

Arguments 

fi leURL, text, {mode} 

• The first argument is the file you are writing to, expressed as a file:// URL. 

• The second argument is the string to be written. 

• The third argument, if supplied, must be "append". If this argument is 
omitted, the contents of the file are overwritten by the string. 

Returns 

true if the string was successfully written to the file, f a 1 se otherwise. 
Example 

The following code attempts to write the string "xxx " to the file mydata.txt and 
displays an alert if the write succeeded. It then attempts to append the string 
" a a a " to the file and displays a second alert if the write succeeded. After executing 
this script, the file mydata.txt will contain the text xxxaaa and nothing else. 

var fileURL = "f i 1 e : ///c | /temp/mydata . txt" ; 
if (DWfile.write(fileURL, "xxx")){ 
alertCWrote xxx to " + fileURL); 

} 

if (DWfile.wn'teCfileURL, "aaa", "append")){ 
al ert( "Appended aaa to " + fileURL); 
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Extensions are not limited to working within the local file system. Dreamweaver 
provides a mechanism for getting information from and sending information to a 
Web server via hypertext transfer protocol (HTTP). This chapter describes the 
HTTP API and how to use it. 



The HTTP APS 

All functions in the HTTP API are methods of the MMHttp object. Most take at 
least a URL as an argument, and most return an object. The default port for URL 
arguments is 80; to specify a port other than 80, append a colon and the port 
number to the URL. For example: 

MMHttp . getTexK "http: //www. myserver.com : 8025" ) ; 

For functions that return an object, the object has two properties: statusCode 
and data. 

statusCode indicates the status of the operation; possible values include but are 
not limited to: 

• 200: Status OK 

• 400: Unintelligible request 

• 404: Requested URL not found 

• 405: Server does not support requested method 

• 500: Unknown server error 

• 503: Server capacity reached 

For a comprehensive list of status codes for your server, check with your Internet 
service provider or system administrator. 
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The value of the data property varies according to the function; possible values 
are specified in the individual function listings. 

Functions that return an object also have a "callback" version. Callback functions 
allow other functions to execute while the Web server processes an HTTP request. 
This is useful if you are making multiple HTTP requests from Dreamweaver. The 
callback version of a function passes its ID and return value directly to the 
function specified as its first argument. 

Optional arguments are enclosed in braces ({ }). 

MMHttp,c!earTemp() 

Description 

Deletes all files in the Configuration/Temp folder inside the Dreamweaver 
application folder. 

Arguments 

None. 

Returns 

Nothing. 

Example 

The following code, when saved in a file inside the Configuration/Shutdown 
folder, removes all files from the Configuration/Temp folder when the user 
quits Dreamweaver: 

<html> 
<head> 

<title>Clean Up Temp Files on Shutdown</ti tl e> 
</head> 

<body onl_oad="MMHttp . cl earTemp( ) "> 

</body> 

</html> 

MMHttp.getFyeQ 

Description 

Gets the file at the specified URL and saves it in the Configuration/Temp folder 
inside the Dreamweaver application folder on the user's hard disk. Dreamweaver 
automatically creates subfolders that mimic the folder structure of the server; 
for example, if the specified file is at http://www.dreamcentral.com/people/ 
index.html, Dreamweaver stores the index.html file in the People folder inside 
the www.dreamcentral.com folder. 
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Arguments 

URL, {prompt}, {saveURL}, {tit! eBarLabel } 

• The first argument is an absolute URL on a Web server; if "http://" is omitted 
from the URL, it is assumed. 

• The second argument is a Boolean value that specifies whether to prompt the 
user to save the file. If saveURL is outside the Configuration/Temp folder, a 
prompt value of f al se is ignored for security reasons. 

• The third argument is the location on the users hard disk where the file 
should be saved, expressed as a file:// URL. If prompt is true or saveURL is 
outside the Configuration/Temp folder, the user can override saveURL in the 
Save dialog box. 

• The fourth argument is the label that should appear in the title bar of the Save 
dialog box. 

Returns 

An object that represents the reply from the server. The data property of this 
object is a string containing the location where the file was saved, expressed as a 
file:// URL. Normally thestatusCode property of the object contains the status 
code received from the server. However, if a disk error occurs while Dreamweaver 
is saving the file on the local drive, the statusCode property contains an integer 
representing one of the following error codes if the operation was not successful: 

• 1 : Unspecified error 

• 2: File not found 

• 3: Invalid path 

• 4: Number of open files limit reached 

• 5: Access denied 

• 6: Invalid file handle 

• 7: Cannot remove current working directory 

• 8: No more directory entries 

• 9: Error setting file pointer 

• 10: Hardware error 

• 11: Sharing violation 

• 12: Lock violation 

• 13: Disk full 

• 14: End of file reached 
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Example 

The following code gets an HTML file, saves all the files in the Configuration/ 
Temp folder, and then opens the local copy of the HTML file in a browser: 

var httpReply = MMHttp.getFi 1 e( "http: //www . dreamcentral .com/^ 
peopl e/prof i 1 es/scott . html " , fal se) ; 
if (httpReply. statusCode == 200){ 

var saveLoc = httpRepl y . data ; 

dw. browse Document ( save Loc) ; 

} 

MMHttp.getpyeCafSbackQ 

Description 

Gets the file at the specified URL, saves it in the Configuration/Temp folder 
inside the Dreamweaver application folder on the user's hard disk, and then 
calls the specified function with the request ID and reply result. When saving 
the file locally, Dreamweaver automatically creates sub folders that mimic 
the directory structure of the server; for example, if the specified file is at 
http://www.dreamcentral.com/people/index.html, Dreamweaver stores the 
index.html file in the People folder inside the www.dreamcentral.com folder. 

Arguments 

cal 1 backFuncti on, URL, {prompt}, {saveURL}, (ti tl eBarLabel } 

• The first argument is the name of the JavaScript function to call when the 
HTTP request is complete. 

• The second argument is an absolute URL on a Web server; if "http://" is 
omitted from the URL, it is assumed. 

• The third argument is a Boolean value that specifies whether to prompt the 
user to save the file. If saveURL is outside the Configuration/Temp folder, a 
prompt value of fal se is ignored for security reasons. 

• The fourth argument is the location on the users hard disk where the file 
should be saved, expressed as a file:// URL. If prompt is true or saveURL is 
outside the Configuration/Temp folder, the user can override saveURL in the 
Save dialog box. 

• The fifth argument is the label that should appear in the title bar of the 
Save dialog box. 

Returns 

An object that represents the reply from the server. The data property of this 
object is a string containing the location where the file was saved, expressed as a 
file:// URL. Normally the statusCode property of the object contains the status 
code received from the server. However, if a disk error occurs while Dreamweaver 
is saving the file on the local drive, the statusCode property contains an integer 
representing an error code. See "MMHttp.getFile()" on page 138 for a list of 
possible error codes. 
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MMHttp.getTextQ 

Description 

Retrieves the contents of the document at the specified URL. 

Arguments 

URL 

The argument is an absolute URL on a Web server; if "http://" is omitted from 
the URL, it is assumed. 

Returns 

An object that represents the reply from the server. The data property of this 
object is a string containing the contents of the document. 

Example 

The following code gets the contents of a file on a Web server and puts it in a new, 
untitled Dreamweaver document: 

var httpReply = MMHttp.getTexK "http: //www. dreamcentral .com/-> 

peopl e/prof i 1 es/1 ori . html " ) ; 

if (httpReply. statusCode == 200){ 

var newDoc = dw . createDocument ( ) ; 

newDoc . document El ement . outerHTML = httpRepl y . data ; 

} 
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MMHttp.getTextCaybackQ 

Description 

Retrieves the contents of the document at the specified URL and passes it to the 
specified function. 

Arguments 

ca 1 IbdckFunc, URL 

• The first argument is the name of the JavaScript function to call when the 
HTTP request is complete. 

• The second argument is an absolute URL on a Web server; if "http://" is 
omitted from the URL, it is assumed. 

Returns 

An object that represents the reply from the server. The data property of this 
object is a string containing the contents of the document. 

Example 

The following code populates a form field with the text returned by the 
MMHttp.GetTextCallbackO function or shows an error message if the function 
returns an error: 

var requestID = MMHttp . getTextCal 1 back ( "httpCal 1 back" , -> 
"www. d rea mcentral . com/i ndex . html " ) 

function httpCal 1 back( request I D , repl y ) { 
if (reply. statusCode == 200) { 

document . theForm. docContents . val ue = reply. data; 
}el se{ 

al ert( " Request #: " + requestID + "returned the following -< 
error: " + repl y . statusCode ) ; 

} 

} 
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MMHttp.postTextQ 



Description 

Performs an HTTP post of the specified data to the specified URL. Typically the 
data associated with a post operation is form-encoded text, but it could be any 
type of data that the server expects to receive. 

Arguments 

URL, dataToPost, {contentType} 

• The first argument is an absolute URL on a Web server; if "http://" is omitted 
from the URL, it is assumed. 

• The second argument is the data to be posted. If the third argument is 

"appl i cati on/x -www- form- url encoded" or omitted, data To Post must be 
form-encoded according to section 8.2.1 of the RFC 1866 specification 
(available at http://www.faqs.org/rfcs/rfcl866.html). 

• The third argument is the content type of the data to be posted. If omitted, this 
argument defaults to "appl i cati on/x-www- form- url encoded ". 

Returns 

An object that represents the reply from the server. The data property of this 
object is a string containing the data resulting from the post operation. 
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MMHttp,postTextCalIback() 



Description 

Performs an HTTP post of the text to the specified URL and passes the reply from 
the server to the specified function. Typically the data associated with a post 
operation is form-encoded text, but it could be any type of data that the server 
expects to receive. 

Arguments 

cal 1 backFunc, URL, dataToPost, {contentTypej 

• The first argument is the name of the JavaScript function to call when the 
HTTP request is complete. 

• The second argument is an absolute URL on a Web server; if "http://" is 
omitted from the URL, it is assumed. 

• The third argument is the data to be posted. If the third argument is 

"appl i cati on/x-www-form-url encoded" or omitted, data must be form- 
encoded according to section 8.2.1 of the RFC 1866 specification (available at 
http ://www.faqs.org/rfcs/ rfc 1 866.html) . 

• The fourth argument is the content type of the data to be posted. If omitted, 
this argument defaults to "appl i cati on/x-www-form-url encoded". 

Returns 

An object that represents the reply from the server. The data property of this 
object is a string containing the data resulting from the post operation. 



144 Chapter 1t> 




CHAPTER 16 

The Database AP 



Database functions allow you to work with structured query language (SQL) 
statements and stored procedures. Using these functions, you can retrieve certain 
database schema information. A database schema is the structure of a database. 
(This structural information is also referred to as metadata.) The structure of a 
database includes the databases table and column names. With the database API 
functions, you can get table and column names from SQL statements and stored 
procedures, get user names and passwords used to establish database connections, 
and show the results of an executed SQL statement or stored procedure. These 
functions are used at design time when users are building their Web applications, 
as opposed to run time, when the Web application is deployed. 

The database functions can be used by any extension. In fact, the UltraDev 
server behavior, data format, and data source API functions make use of the 
database functions. 

The following example shows how the server behavior function, 
getDynami cBi ndi ngs ( ), is defined for Recordset. (The file, Recordset.js, 
is located in the /Configuration/ServerBehaviors/ASP folder.) 



145 



Notice that the MMDB . getCol umnLi st( ) function is used. 

functi on getDynami cBi ndi ngs(el ementNode) 
{ 

van ss = fi ndSSrec(el ementNode , LABEL_Type) 

van connString = ss . acti veconnecti on 
var connName = ss . connecti onName 
van statement = ss. source 
var rsName = ss . rsName 

var pa = new Array ( ) 

if ( Stri ng( ss . ParamArray ) != "undefined") 
{ 

for (var i = 0; i < ss . Pa ramArray . 1 ength ; i++) 
{ 

pa [i ] = new Array ( ) 

pa[i][0] = ss . ParamArray [i ]. name 

pa[i][l] = ss . ParamArray [i ]. val ue 

} 

} 

var statement = Repl acePa ramsWi thVal s ( statement , pa) 
return MMDB . getCol umnLi st(connName , statement) 

} 

Database API functions 

The following list describes some of the arguments common to the 
database functions: 

• Most database functions use a connection name as an argument. You can see a 
list of valid connection names in the UltraDev Connection Manager, or you 
can use MMDB . getConnecti on Li st( ) to get a list of all the connection names 
p rogrammatically. 

• Stored procedures often require parameters. There are two ways of specifying 
parameter values for database functions. First, you can provide an array of 
parameter values (paramVal uesArray). If you specify only parameter 
values, the values need to be in the sequence in which the stored procedure 
requires the parameters. Second, you specify parameter values to provide 

an array of parameter names (pa raniNanieArray). (You can use the 
MMDB.getSPParamsAsString( ) function to get the parameters of the 
stored procedure.) If you provide parameter names, the values specified in 
paramVal uesArray need to be in the sequence in which the parameter 
names were specified in pa ramNameArray. 
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getCofdFus3onOsnList(5 

Availability 

Dreamweaver UltraDev 4.0 
Description 

Gets the ColdFusion DSNs from the site server, using thegetRdsUserNameO 
and getRdsPassworcK ) functions. 

Arguments 

None. 

Returns 

An array containing the ColdFusion DSNs that are defined on the server for the 
current site. 

MyOB D getCoiumnAndTypeList{) 

Availability 

Dreamweaver UltraDev 1 .0 
Description 

Gets a list of columns and their types from an executed SQL SELECT statement. 
Arguments 

connName, statement 

• connName is the UltraDev connection name as specified in the Connection 
Manager. It is used to make a database connection to a live data source. 

• stat emen t is the SQL SELECT statement to execute. 
Returns 

An array of strings representing a list of columns (and their types) that match the 
SELECT statement, or an error if the SQL statement was invalid or the connection 
could not be made. 

Example 

The code var columnArray = 

MMDB.getCol umnAndTypeLi st( "EmpDB" , "Sel ect * from Employees") 
returns the following array of strings: 

col umnArray[0] = "EmpName" , col umnArray [1 ] = "varchar", -< 
col umnArray [2] = " EmpFi rstName" , col umnArray [3] = "varchar", -< 
col umnArray[4] = "Age", col umnArray [5] = "integer" 
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MMDB.getColumnUstQ 

Availability 

Dreamweaver UltraDev 1 .0 
Description 

Gets a list of columns from an executed SQL SELECT statement. 
Arguments 

connName, statement 

• connName is an UltraDev connection name as specified in the Connection 
Manager. It is used to make a database connection to a live data source. 

• statement is the SQL SELECT statement to execute. 
Returns 

An array of strings representing a list of columns that match the SELECT 
statement, or an error if the SQL statement was invalid or the connection could 
not be made. 

Example 

Thecode var columnArray - MMDB . getCol umnLi st( " EmpDB" , "Sel ect * 
from Empl oyees " ) returns the following array of strings: 

col umnArray [0] = " EmpName" , col umnArray [1 ] = " EmpFi rstName" , -< 
col umnArray[2] = "Age" 
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MMDB.getColumnsOfTableQ 

Availability 

Dreamweaver UltraDev 1 .0 
Description 

Gets a list of all the columns in the specified table. 
Arguments 

connName, tableName 

• connName is the UltraDev connection name as specified in the Connection 
Manager. It is used to make a database connection to a live data source. 

• tab 1 eName is the name of a table in the database specified by connName. 
Returns 

An array of strings; each string is the name of a column in the table. 
Example 

The statement MMDB . getCol umnsOfTabl e ( " EmpDB" , " Empl oyees" ) ; returns 
the following strings: 

[ " Emp ID", " Fi rstName" , " LastName" ] 

MMDB.getConnectgonUstQ 

Availability 

Dreamweaver UltraDev 1 .0 
Description 

Gets a list of all the connection strings defined in the Connection Manager. 

Arguments 

None. 

Returns 

An array of strings; each string is the name of a connection as it appears in the 
Connection Manager. 

Example 

A call to MMDB . getConnecti on Li st( ) could return the strings [ " EmpDB" , 
"Test", "TestEmp" ]. 
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MMDB,getConnect§onName() 

Availability 

Dreamweaver UltraDev 1 .0 
Description 

Gets the connection name corresponding to the specified connection string. 
This function is useful when you need to reselect a connection name in the 
user interface from data on the page. 

If you have a connection string that references two different drivers, you 
can specify both the connection string and the driver that corresponds to 
the connection name you want returned. For example, you could have 
two connections: 

Connection 1 has the following properties: 

Connecti onStri ng=" jdbc : i netdae : vel cro-qa -5 : 1433?database=pubs " 
Dri verName="com. i net . tds . TdsDri ver" 

Connection2 has the following properties: 

Connecti onStri ng=" jdbc : i netdae : vel cro-qa -5 : 1433?database=pubs " 
Dri verName="com. i net . tds .TdsDri ver2" 

The connection strings for both Connection 1 and Connection2 are the same. 
Connection2 connects to a more recent version of TdsDri ver. You should pass 
the driver name to this function to fully qualify the connection name you 
would like returned. 

Arguments 

connStri ng, (dri verName} 

• connStri ng is the connection string used to get the connection name. 

• dri ver Name is an optional argument that further qualifies connStri ng. 
Returns 

A connection name string corresponding to the connection string. 
Example 

The following code returns the string " EmpDB " : 

var connect!' onName = MMDB . getConnecti onName -> 
( "dsn=EmpDB ; ui d=; pwd=" ) ; 
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MMDB,getConnect§onStnng() 

Availability 

Dreamweaver UltraDev 1 .0 
Description 

Gets the connection string associated with the specified connection name. 

Arguments 

connName 

connName is an UltraDev connection name as specified in the Connection 
Manager. It is used to make a database connection to a live data source. 

Returns 

A string corresponding to the connection name. 
Example 

The code var connecti onSt ri ng = MMDB . getConnecti onStri ng ( " EmpDB" ) 
returns different strings for an ADO or JDBC connection. 

For an ADO connection, the following string could be returned: 

"dsn=EmpDB ; ui d=; pwd=" ; 

For a JDBC connection, the following string could be returned: 

M jdbc:inetdae:192.168.64.49:1433?database=pubs&user=JoeUser&^ 
password=joesSecret." 

MMDB.getDnverName() 

Availability 

Dreamweaver UltraDev 1 .0 
Description 

Gets the driver name associated with the specified connection. Only a JDBC 
connection has a driver name in Dreamweaver UltraDev 1.0. 

Arguments 

connName 

connName is an UltraDev connection name as specified in the Connection 
Manager. It is used to make a database connection to a live data source. 

Returns 

A string containing the driver name. 
Example 

The statement MMDB . getDri verNaine ("EmpDB"); might return the 
following string: 

" jdbc/oracl e/dri ver/ JdbcOracl e" 
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MyDELgetFasswordQ 

Availability 

Dreamweaver UltraDev 1 .0 
Description 

Gets the password used for the specified connection. 

Arguments 

connName 

connName is an UltraDev connection name as specified in the Connection 
Manager. It is used to make a database connection to a live data source. 

Returns 

A password string associated with the connection name. 
Example 

The statement MMDB . get Pas sword ("EmpDB"); might return " joessecret". 

MyDB.getRuntimeConnectionTypeQ 

Availability 

Dreamweaver UltraDev 1 .0 
Description 

Returns the run-time connection type of the specified connection name. 

This function can return one of the following values: "ADO", "A DO DSN", "JDBC", 

or"CFDSN". 

Arguments 

connName 

connName is the UltraDev connection name as specified in the Connection 
Manager. It is used to make a database connection to a live data source. 

Returns 

A string corresponding to the connection type. 
Example 

The following code would return the string "ADO " for an ADO connection: 

var connecti onType = MMDB . getRunti meConnecti onType ("EmpDB") 
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MMDB.getSFColumnLJstQ 

Availability 

Dreamweaver UltraDev 1 .0 
Description 

Gets a list of result set columns that are generated by a call to the specified 
stored procedure. 

Arguments 

connName, statement, paramVal uesArray 

• connName is an UltraDev connection name as specified in the Connection 
Manager. It is used to make a database connection to a live data source. 

• statemen t is the name of the stored procedure that returns the result set 
when executed. 

• paramVal uesArray is an array containing a list of design-time parameter test 
values. Specify the parameter values in the order in which the stored procedure 
expects them. You can use the MMDB . getSPPa rams As St ri ng( ) function to get 
the parameters of the stored procedure. 

Returns 

An array of strings representing the list of columns. This function returns an error 
if the SQL statement is invalid or if the connection string is wrong. 

Example 

The following code could return a list of result set columns that were generated 
from the executed stored procedure, getNewEmpl oyeesMaki ngAt Least: 

var paramValueArray = new Array ( "2/1/2000" , "50000") 
var col umnArray = MMDB . getSPCol umnLi st ( " EmpDB" , -> 
"getNewEmpl oyeesMaki ngAt Least" , paramVal ueArray ) 

These are the returned values: 

col umnArray[0] = "EmpID", col umnArray [1 ] = "LastName", -> 
col umnArray [2] =" sta rtDate" , col umnArray [3] = "salary" 
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MMDB.getSPColumnLgstNamedParamsQ 



Availability 

Dreamweaver UltraDev 1 .0 
Description 

Gets a list of result set columns that are generated by a call to the specified 
stored procedure. 

Arguments 

connName, statement, paramNameArray, paramVal uesArray 

• connName is an UltraDev connection name as specified in the Connection 
Manager. It is used to make a database connection to a live data source. 

• statemen t is the name of the stored procedure that returns the result set 
when executed. 

• paramNameArray is an array containing a list of parameter names. You can 
use the MMDB . getSPPa ramsAsStri ng( ) function to get the parameters of the 
stored procedure. 

• paramVa 1 uesArray is an array containing a list of design-time parameter test 
values. Optional, specify if the procedure requires parameters when executed. If 
you have provided parameter names in paramNameArray, specify the parameter 
values in the same order as their corresponding parameter names appear in 
paramNameArray. If you did not provide paramNameArray, specify the values 
in the order in which the stored procedure expects them. 

Returns 

An array of strings representing the list of columns. This function returns an error 
if the SQL statement is invalid or if the connection string is wrong. 

Example 

The following code could return a list of result set columns that were generated 
from the executed stored procedure, getNewEmpl oyeesMaki ngAt Least: 

var paramNameArray = new Array (" sta rtDate" , "salary") 

var paramVal ueArray = new Array ( "2/1/2000" , "50000") 

var columnArray = MMDB . getSPCol umnLi stNamedPa rams (" EmpDB" 

"getNewEmpl oyeesMaki ngAtLeast" , paramNameArray, paramVal ueArray) 

These are the returned values: 

col umnArray[0] = "EmpID", col umnArray [1 ] = "LastName",^ 
col umnArray [2] =" sta rtDate" , col umnArray [31 = "salary" 
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MMDB,getSPParamsAsStnng() 

Availability 

Dreamweaver UltraDev 1 .0 
Description 

Gets a comma-delimited string containing the list of parameters that the stored 
procedure takes. 

Arguments 

connName, procName 

• connName is an UltraDev connection name as specified in the Connection 
Manager. It is used to make a database connection to a live data source. 

• procName is the name of the stored procedure. 
Returns 

A comma-delimited string containing the list of parameters that the stored 
procedure requires. The parameters' names, direction, and data type are included, 
separated by semicolons (;). 

Example 

The code MMDB . getSPPa rams As St ri ng 

( " EmpDB" , "getNewEmpl oyeesMa ki ngAt Least " ) could return a string of form 

name start Date ;di recti on : i n ; datatype : date , 
sal a ry ; di recti on : i n ; datatype : i nteger 

Here, the stored procedure, getNewEmpl oyeesMa ki ngAt Lea st, has two 
parameters: startDate and Sal ary. For startDate, the direction is i n and the 
data type is da te. For sa 1 a ry, the direction is i n and the data type is da te. 
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MMDELgetTabiesQ 

Availability 

Dreamweaver UltraDev 1 .0 
Description 

Gets a list of all the tables defined for the specified database. Each table object 
has three properties: tabl e, schema, and catal og. Tabl e is the name of the table, 
schema is the name of the schema containing the table, and ca ta 1 og is the 
catalog containing the table. 

Arguments 

conn Name 

connName is an UltraDev connection name as specified in the Connection 
Manager. It is used to make a database connection to a live data source. 

Returns 

An array of objects; each object has three properties: table, schema, 
and catal og. 

Example 

The statement MMDB . getTabl es ( " EmpDB" ) ; might produce an array of two 
objects. The first object's properties might be the following: 

objectl [tabl e : " Empl oyees" , schema : "personnel " , catal og : "syscat" ] 

The second object s properties might be the following: 

object2[tabl e : "Departments" , schema : "demo" , catal og : "syscat2" ] 

MMDB.getUserNameO 

Availability 

Dreamweaver UltraDev 1.0 
Description 

Returns a user name for the specified connection. 

Arguments 

connName 

connName is an UltraDev connection name as specified in the Connection 
Manager. It is used to make a database connection to a live data source. 

Returns 

A user name string associated with the connection name. 
Example 

The statement MMDB . getUserName ("EmpDB"); might return "ami t". 
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MMDELgetViewsQ 



Availability 

Dreamweaver UltraDev 4.0 
Description 

Gets a list of all the views defined for the specified database. Each view object 
has properties: catal og, schema, and vi ew. Catal og or schema is used for 
restricting/filtering the number of views that pertain to an individual schema 
name or catalog name defined as part of the connection information. 

Arguments 

conn Name 

connName is an UltraDev connection name as specified in the Connection 
Manager. It is used to make a database connection to a live data source. 

Returns 

An array of view objects; each object has three properties: catal og, schema, 
and vi ew. 

Example 

The following example returns the views for a given connection value, 

CONN_LIST.getValue(): 

var viewObjects = MMDB . getVi ews ( CON N_L I ST . getVal ue( ) ) 

for (i =0; i < vi ewObjects . 1 ength ; 

{ 

thisView = vi ewObjects[i ] 
thisSchema = Tri m( thi sVi ew . schema ) 
if (thi sSchema . 1 ength == 0) 
{ 

thisSchema = Trim(thi sView. catal og) 

} 

if (thi sSchema . 1 ength > 0) 
{ 

thi sSchema += " . " 

} 

views. push( Stri ng( thi sSchema + thi sVi ew . vi ew) ) 
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MMDB.showConnectionygrDBalogO 

Availability 

Dreamweaver UltraDev 1 .0 
Description 

Displays the Connection Manager dialog box. 

Arguments 

Nothing. 

Returns 

Nothing. The Connection Manager dialog box appears. 

MMDB,showResLiltset{) 

Availability 

Dreamweaver UltraDev 1 .0 
Description 

Displays a dialog box with the results of executing the specified SQL statement. 
The dialog box displays a tabular grid, with the header reflecting the column 
information and data of the result set generated by the executed stored procedure. 
If the connection string or the SQL statement is invalid, an error appears. You can 
use this function to verify the validity of the SQL statement. 

Arguments 

connName, SQLstatement 

• connName is an UltraDev connection name as specified in the Connection 
Manager. It is used to make a database connection to a live data source. 

• SQLstatement is the SQL SELECT statement. 
Returns 

Nothing. This function returns an error if the SQL statement is invalid or if the 
connection string is wrong. 

Example 

The following code displays the results of the executed SQL statement: 

MMDB . showResul tset ( " EmpDB" , " Sel ect EmpName , EmpFi rstName , Age f roim 
Empl oyees" ) 
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MMDB.showSFResultsetQ 

Availability 

Dreamweaver UltraDev 1 .0 
Description 

Displays a dialog box with the results of executing the specified stored procedure. 
The dialog box displays a tabular grid, with the header reflecting the column 
information and data of the result set generated by the executed stored procedure. 
If the connection string or the stored procedure is invalid, an error appears. You 
can use this function to verify the validity of the stored procedure. 

Arguments 

connName, procName, paramVal uesArray 

• connName is the UltraDev connection name as specified in the Connection 
Manager. It is used to make a database connection to a live data source. 

• p roc Name is the name of the stored procedure to execute. 

• paramVal uesArray is an array containing a list of design-time parameter test 
values. Specify the parameter values in the order in which the stored procedure 
expects them. You can use the MMDB . getSPPa rams As St ri ng( ) function to get 
the parameters of the stored procedure. 

Returns 

Nothing. This function returns an error if the SQL statement is invalid or if the 
connection string is wrong. 

Example 

The following code displays the results of the executed stored procedure: 

var paramVal ueArray = new Array ( "2/1/2000" , "50000") 

MMDB . showSPResul tset( " EmpDB" , "getNewEmpl oyeesMaki ngAt Least" , -i 

paramVal ueArray) 
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MMDB.showSPResultsetNamedParamsQ 



Availability 

Dreamweaver UltraDev 1 .0 
Description 

Displays a dialog box with the results of executing the specified stored procedure. 
The dialog box displays a tabular grid, with the header reflecting the column 
information and data of the result set generated by the executed stored procedure. 
If the connection string or the stored procedure is invalid, an error appears. 
You can use this function to verify the validity of the stored procedure. This 
function differs from MMDB.showSPResultsetO because you can specify the 
parameter values by name, instead of in the order in which the stored procedure 
expects them. 

Arguments 

connName, procName, paramNameArray, paramVal uesArray 

• connName is an UltraDev connection name as specified in the Connection 
Manager. It is used to make a database connection to a live data source. 

• p roc Name is the name of the stored procedure that returns the result set 
when executed. 

• paramNameA may is an array containing a list of parameter names. You can 
use the MMDB . getSPPa ramsAsStri ng( ) function to get the parameters of the 
stored procedure. 

• paramVa 1 uesArray is an array containing a list of design-time parameter 
test values. 

Returns 

Nothing. This function returns an error if the SQL statement is invalid or if the 
connection string is wrong. 

Example 

The following code displays the results of the executed stored procedure: 

var paramNameArray = new Array (" sta rtDate" , "salary") 
var paramVal ueArray = new Array ( "2/1/2000" , "50000") 
MMDB . showS P Res ul t set Named Pa rams ( " EmpDB" , "getNewEmpl oyees^ 
Maki ngAtLeast" , paramNameArray, paramVal ueArray ) 
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CHAPTER 17 

The JavaBean API 



This chapter explains the APIs for JavaBeans, the MMJB*( ) functions are 
JavaScript hooks that invoke Java introspection calls for JavaBean support. 
These functions get class names, methods, properties, and events from the 
JavaBean, which can be displayed in your Dreamweaver user interface. To use 
these JavaScript functions and enable Dreamweaver to access your JavaBean, 
your JavaBean must reside in the Configuration/Cl asses folder. 

Note: packageName.className - is one single String input. 

MMJB,getProperties{) 

Availability 

Dreamweaver UltraDev 4.0 
Description 

Introspects the bean class and returns its properties. 
Arguments 

packageName. className 

packageName . cl assName is the name of the class, which is part of the classpath. 
It must be a Java .jar or .zip Java archive residing in your system class path or a 
.class file that is installed in the Configuration/Classes folder. 

Returns 

A string array of the JavaBean properties. On error, returns an empty array. 
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MMJB,getMethods() 

Availability 

Dreamweaver UltraDev 4.0 
Description 

Introspects the bean class and returns its methods. 
Arguments 

packageName . cl assName 

packageName . cl assName is the package name of the class, which is part of the 
classpath. It must be a Java .jar or .zip Java archive. 

Returns 

A string array of the JavaBean methods. On error, returns an empty array. 

MMJB.getEvents{) 

Availability 

Dreamweaver UltraDev 4.0 
Description 

Introspects the bean class and returns its events. 
Arguments 

packageName . cl assName 

packageName . c 1 assName is the package name of the class, which is part of the 
classpath. It must be a Java .jar or .zip Java archive. 

Returns 

A string array of the JavaBean events. On error, returns an empty array. 
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MMJB.getSndexedFropertsesQ 

Availability 

Dreamweaver UltraDev 4.0 
Description 

Introspects the bean class and returns its indexed properties. Indexed properties 
are design patterns that behave like collections. 

Arguments 

packageName . cl assName 

packageName . cl assName is the package name of the class, which is part of the 
classpath. It must be a Java .jar or .zip Java archive. 

Returns 

A string array of indexed properties of the JavaBean. On error, returns an 
empty array. 

MMJB,getClasses{) 

Availability 

Dreamweaver UltraDev 4.0 
Description 

Reads all the JavaBean class names from the Configuration/Cl asses folder. 

Arguments 

None. 

Returns 

A string array of class names that live in Configuration/ Classes folder. On error, 
returns an empty array. 
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MMJB,getClassesFromPackage() 

Availability 

Dreamweaver UltraDev 4.0 
Description 

Reads all the JavaBean classes from the package. 
Arguments 

packageName.pathName 

packageName . pathName is the path to the package. It must be a Java .jar or .zip 
Java archive. For example, C : \ jdbcdri vers\Una2000_Enterpri se . zi p. 

Returns 

A string array of class names inside the particular .jar or .zip Java file. On error, 
returns an empty array. 

MyJB.getErrorMessageQ 

Availability 

Dreamweaver UltraDev 4.0 
Description 

Gets the last error message from Dreamweaver that occurred while using the 
MMJB interface. 

Arguments 

None. 

Returns 

A string of the Dreamweaver message from the last error. 
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CHAPTER 18 

The Source Control Integration API 



The source control integration API allows you to write DLLs to extend the 
Dreamweaver check in/check out feature using the features of other source control 
systems (such as Sourcesafe, CVS, or Whirlwind). These API functions can also be 
used to describe how the Dreamweaver user can interact with the integrated 
source control system. 

You implement this API by writing a C-level DLL/shared code fragment that 
adheres to the API defined in this chapter. There is a minimum set of API 
functions that you must support in order for Dreamweaver to integrate 
with a source control system. The DLLs are placed in the Configuration/ 
SourceControl folder. 

When started, Dreamweaver loads each DLL file. Dreamweaver determines which 
of the APIs the DLL supports by calling GetProcAddress ( ) on the various APIs. 
If an address doesn't exist, Dreamweaver assumes the DLL does not support the 
API. If the address exists, Dreamweaver uses the DLLs version of the function to 
support the functionality. When a Dreamweaver user defines or edits a site and 
then chooses the Web Server SCS tab, the choices corresponding to the DLLs that 
were loaded from the Configuration/SourceControl folder appear (in addition to 
the standard items) on the tab. 

To add custom items to the Site > Source Control menu, add the following code 
in the Site menu in the menus .xml file: 

<menu name="Source Control" i d=" DWMenu_Mai nSi te_Si te_Source^ 

Control "Xmenuitem dynamic name="None"f i 1 e="Menus/MM/^ 

Fi 1 e_SCSItems . htm" i d="DWMenu_Mai nSi te_Si te_NewFeatures_Defaul t " /> 

</menu> 
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Integration with Dreamweaver 



When a Dreamweaver user chooses server connection, file transfer, or Design 
Notes features, Dreamweaver calls the DLL's version of the corresponding API 
function (Connect ( ), Di s connect ( ), Get( ), Put (), Checki n( ), Checkout ( ), 
Undocheckout ( ), and Synchronize( )).The DLL is responsible for handling the 
request, including displaying dialog boxes that gather information or allow the 
user to interact with the DLL. The DLL is also responsible for displaying 
information or error messages. 

The source control system can optionally support Design Notes and Check In/ 
Check Out. The Dreamweaver user enables Design Notes in source control 
systems by choosing the Design Notes tab in the Define Sites dialog and checking 
the box to enable the feature; this is the same way that they enable Design Notes 
with FTP and LAN in version 3.0. If the source control system does not support 
Design Notes and the user wants to use this feature, Dreamweaver transports 
Design Note (.mno) files to maintain the Design Notes (as it does with FTP and 
LAN in version 3.0). 

Check In/ Check Out is treated differently than the Design Notes feature; if the 
source control system supports it, the user cannot override its use from the Design 
Notes dialog box. If the user tries to override the source control system, an error 
message appears. 

Adding source control system functsonaHty 

You can add source control system functionality to Dreamweaver by writing a 
GetNewFeatures handler that returns a set of menu items and corresponding C 
functions. For example, if you were writing a Sourcesafe DLL and wanted to allow 
Dreamweaver users to see the history of a file, you could write a GetNewFeatures 
handler that returned the History menu item and the C function name of 
hi story. Then, when the user right-clicks a file, the History menu item is one of 
the items on the menu. If a user chooses the History menu item, Dreamweaver 
calls the history function, passing the selected file(s) to the DLL. You would then 
have the DLL display the History dialog box so the user could interact with it just 
like they would if using Sourcesafe. 

The source control integration API 
required functions 

The source control integration API has both required and optional functions. The 
functions listed in this section are required. 
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SGSJBetAgentlnfoQ 



Description 

Asks the DLL to return its name and description, which are displayed in the 
Define Sites dialog. Name appears in the Server Access pop-up menu (for 
example, sourcesafe, webdav, perforce) and description just below the 
pop-up menu. 

Arguments 

name, version, description, dwAppVersion 

• n a me is the name of the source control system. Name appears in the combo box 
for selecting a source control system in the Source Control tab of the Define 
Sites dialog box. The name can be a maximum of 32 characters. 

• version is a. string indicating the version of the DLL. Version appears in the 
Source Control tab of the Define Sites dialog. The version can be a maximum 
of 32 characters. 

• descript i on is a string indicating the description of the source control system. 
Description appears in the Source Control tab of the Define Sites dialog. The 
description can be a maximum of 256 characters. 

• dwApp Ve rs ion is a string representing the version of Dreamweaver that is 
calling the DLL. The DLL can use this string to determine the version and 
language of Dreamweaver. 

Returns 

true if successful, fal se if not. 

SCS^ConnectQ 

Description 

Connects the user to the source control system. If the DLL does not have login 
information, the DLL is responsible for displaying a dialog box to prompt the user 
for the information and for storing the data for later use. 

Arguments 

connectionData, siteName 

• connecti onData is a handle to the data the agent wants Dreamweaver to pass 
to it when calling other API functions. 

• si teName is a string pointing to the name of the site. The site name can be a 
maximum of 64 characters. 

Returns 

true if successful, fal se if not. 
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SCSJSisconnectQ 

Description 

Disconnects the user from the source control system. 

Arguments 

connecti onData 

connecti on Data is a pointer to the agents data that was passed into 
Dreamweaver during the Connect ( ) call. 

Returns 

true if successful, fal se if not. 

SCSJsConnected{) 

Description 

Determines the state of the connection. 

Arguments 

connectionData 

connecti onDa ta is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

Returns 

true if connected, fal se if not. 

SCSJBetRootFolderLengthQ 

Description 

Returns the length of the name of the root folder. 

Arguments 

connect!' onData 

connect! onData is a pointer to the agents data that was passed into 
Dreamweaver during the C o n n e c t ( ) call . 

Returns 

An integer representing the length of the name of the root folder. If the function 
returns < 0, Dreamweaver considers it an error and tries to retrieve the error 
message from the DLL if supported. 
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SGSJ3etRootFoider() 

Description 

Returns the name of the root folder. 
Arguments 

connecti onData, remotePath, folderLen 

• connect! onData is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• remote? a th is a buffer where the full remote path of the root folder is stored. 

• folderLen is an integer indicating the length of remotePath. This is the value 
returned from GetRootFol der Length. 

Returns 

true if successful, fal se if not. 

5C8J3etFolderListLength(5 

Description 

Returns the number of items in the passed-in folder. 
Arguments 

connect! onData, remotePath 

• connect! onData is a pointer to the agents data that was passed into 
Dreamweaver during the Connect ( ) call. 

• remotePa th is the fully qualified path of the remote folder that the DLL 
checks for the number of items. 

Returns 

An integer indicating the number of items in the current folder. If the function 
returns < 0, Dreamweaver considers it an error and tries to retrieve the error 
message from the DLL, if supported. 
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SGSJ3etFo!derList() 

Description 

Returns a list of files and folders in the passed-in folder, including pertinent 
information such as modified date, size, and whether the item is a folder or file. 

Arguments 

connect! onData, remotePath, i temii st, numl terns 

• connect! onData is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• remote Pa th is the fully qualified path of the remote folder that the DLL 
checks for the number of items. 

• 1 temL 1st is a preallocated list of i tern Info structures. 

• numl terns is the number of items allocated for the i temLi s t (returned from 

GetFol derLi st Length). 

Returns 

true if successful, fal se if not. 

SCSJ3etQ 

Description 

Gets a list of files or folders and stores them locally. 
Arguments 

connect! onData, remotePathLi st, / oca] PathLi st, numltems 

• connect! onData is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• remotePa thListisa list of fully qualified remote file or folder paths to get. 

• 1 ocal PathLi st is a mirrored list of fully qualified local file or folder paths. 

• numltems is the number of items in each list. 
Returns 

true if successful, fal se if not. 
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scs„Put() 

Description 

Puts a list of local files or folders into the source control system. 
Arguments 

connecti onData, 1 ocal PathLi st, remotePathLi st, numltems 

• connecti onData is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• / ocal PathLi st is a list of fully qualified local file or folder paths to put. 

• remotePa thiist is a mirrored list of fully qualified remote file or folder paths. 

• numltems is the number of items in each list. 
Returns 

true if successful, fal se if not. 

5CSJS!ewFoIder() 

Description 

Creates a new folder. 

Arguments 

connecti onData, remotePath 

• connecti onData is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• remotePa th is the fully qualified name of the remote folder the DLL creates. 
Returns 

true if successful, fal se if not. 

5CSJ3eietG{) 

Description 

Deletes a list of files or folders from the source control system. 
Arguments 

connecti onData, remotePathLi st, numltems 

• connectionDa ta is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• remotePa th List is a list of fully qualified remote file or folder paths to delete. 

• numl terns is the number of items in remotePathLi st. 
Returns 

true if successful, fal se if not. 
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SCSJ?ename{) 



Description 

Renames or moves a file or folder depending on the values specified for 

ol dRemotePath and newRemotePath. For example, if ol dRemotePath equals 
"$/fol derl/f i 1 el " and newRemotePath equals "$/fol derl/renamef i 1 el", 
filel is renamed to renamefilel and is located in folderl. 

If ol dRemotePath equals "$/fol derl/f i 1 el " and newRemotePath equals 
"$/fol derl/subfol derl/f i 1 el ", filel is moved to the subfolderl directory. 

To find out if an invocation of this function is a move or a rename, check 
the parent paths of the two input values; if they are the same, the operation 
is a rename. 

Arguments 

connecti onData, ol dRemotePath, newRemotePath 

• connecti onData is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• o 1 d Remote Pa th is a fully qualified remote file or folder path to rename. 

• newRemotePa th is the fully qualified remote path of the new name for the 
file or folder. 

Returns 

true if successful, false if not. 
SCSJtemExastsQ 

Description 

Determines whether or not a file or folder exists on the server. 
Arguments 

connecti onData, remotePath 

• connecti onData is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• remote Pa th is a fully qualified remote file or folder path. 
Returns 

true if exists, fal se if not. 
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The source control integration API 
optional functions 

The source control integration API has both required and optional functions. The 
functions in this section are optional. 

SGSJ3etConnectionlnfo{) 

Description 

Displays a dialog box to allow the user to change or set the connection 
information for this site. Does not make the connection. This is called when the 
user clicks the "Settings..." button in the Remote Info section of the Define Sites 
dialog box. 

Arguments 

connect! onData, siteName 

• connect i onData is a handle to data that the agent wants Dreamweaver to pass 
it when calling other API functions. 

• si teName is a string pointing to the name of the site, which cannot exceed 
64 characters. 

Returns 

true if successful, fal se if not. 

SCS^SiteDeletedO 

Description 

Notifies the DLL that the site has been deleted or that the site is no longer tied to 
this source control system, indicating that the source control system can delete its 
persistent information for this site. 

Arguments 

siteName 

s i teName is a string pointing to the name of the site, which cannot exceed 
64 characters. 

Returns 

true if successful, fal se if not. 
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SGSJSiteRenamedQ 



Description 

Notifies the DLL when the user has renamed the site so that it can update its 
persistent information about the site. 

Arguments 

ol dSi teName, newSi teName 

• oldSi teName is a string pointing to the original name of the site before it was 
renamed, which cannot exceed 64 characters. 

• new Si teName is a string pointing to the new name of the site after it was 
renamed, which cannot exceed 64 characters. 

Returns 

true if successful, fal se if not. 

SCSJSetNismNewFeaturesQ 

Description 

Returns the number of new features to add to Dreamweaver (for example, File 
History, Differences, and so on). 

Arguments 

None. 

Returns 

An integer representing the number of new features to add to Dreamweaver. If the 
function returns < 0, Dreamweaver considers it an error and tries to retrieve the 
error message from the DLL, if supported. 
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SGSJ3etNewFeatiires{) 

Description 

Returns a list of menu items to add to the Dreamweaver main and context menus. 
For example, the Sourcesafe DLL could add History and File Differences to the 
main menu. 

Arguments 

menultemii st, menultemii st, enabl erLi st, numNewFeatures 

• menuItemL is t is a string list populated by the DLL; it specifies the menu items 
to add to the main and context menus. Each string can contain a maximum of 
32 characters. 

• fundi on Li st is populated by the DLL; it specifies the routines in the DLL to 
call when the user chooses the corresponding menu item. 

• enabl erLi st is populated by the DLL; it specifies the routines in the DLL to 
call when Dreamweaver needs to determine whether the corresponding menu 
item is enabled. 

• numNewFea tures is the number of items being added by the DLL; this is 
retrieved from the Get NumNewFea tures ( ) call. 

Returns 

true if successful, fal se if not. 

SCSJBetCheckoutNameQ 

Description 

Returns the checkout name of the current user. If unsupported by the source 
control system and this feature is enabled by the user, uses the Dreamweaver 
internal checkin/out functionality, which transports .lck files to and from the 
source control system. 

Arguments 

connecti onData, checkOutName, emai 1 Address 

• connecti onData is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• checkOutName is the checkout name of the current user. 

• ema i 1 Address is the email address of the current user. 
Returns 

true if successful, fal se if not. 
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SGS^CheckmQ 



Description 

Checks a list of local files or folders into the source control system. The DLL is 
responsible for making the file read-only. If unsupported by the source control 
system and this feature is enabled by the user, uses the Dreamweaver internal 
checkin/out functionality, which transports .lck files to and from the source 
control system. 

Arguments 

connecti onData, 1 ocal PathLi st, remotePathLi st, successLi st, numltems 

• connecti onData is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• 1 ocal PathLi st is a list of fully qualified local file or folder paths to check in. 

• remotePa thL is t is a mirrored list of fully qualified remote file or folder paths. 

• successLi st is a list of Boolean values populated by the DLL to let 
Dreamweaver know which of the corresponding files was successfully checked in. 

• numltems is the number of items in each list. 
Returns 

true if successful, fal se if not. 

SCS^Checkout{) 

Description 

Checks out a list of local files or folders from the source control system. The DLL 
is responsible for granting the privileges that allow the file to be writeable. If 
unsupported by the source control system and this feature is enabled by the user, 
uses the Dreamweaver internal checkin/out functionality, which transports .lck 
files to/from the source control system. 
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Arguments 

connecti onData, remotePathLi st, 1 ocal PathLi st, successLi st, numltems 

• connecti onData is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• remote Pa thList is a list of fully qualified remote file or folder paths to 
check out. 

• 1 ocal PathL 1st is a mirrored list of fully qualified local file or folder paths. 

• successLi st is a list of Boolean values populated by the DLL to let 
Dreamweaver know which of the corresponding files was successfully 
checked out. 

• numltems is the number of items in each list. 
Returns 

true if successful, fal se if not. 

SCSJindoCheckoutQ 

Description 

Undoes the checkout status of a list of files or folders. The DLL is responsible for 
making the file read-only. If unsupported by the source control system and this 
feature is enabled by the user, uses the Dreamweaver internal checkin/out 
functionality, which transports .lck files to/from the source control system. 

Arguments 

connecti onData, remotePathLi st, 1 ocal PathLi st, successLi st, numltems 

• connecti onData is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• remote Pa thList is a list of fully qualified remote file or folder paths on which 
to undo the check out. 

• 1 ocal PathLi st is a mirrored list of fully qualified local file or folder paths. 

• successLi st is a list of Boolean values populated by the DLL to let 
Dreamweaver know which corresponding files' check outs were 
successfully undone. 

• numltems is the number of items in each list. 
Returns 

true if successful, fal se if not. 
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SGSJ3etNiimCheckedQut() 

Description 

Returns the number of people who have a file checked out. 
Arguments 

connect!' onData, remotePath 

• connect! on Data is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• remotePa th is the fully qualified remote file or folder path to check to see how 
many users have it checked out. 

Returns 

An integer representing the number of people who have the file checked out. If 
the function returns < 0, Dreamweaver considers it an error and tries to retrieve 
the error message from the DLL if supported. 

SC5J3etReCheckoutList() 

Description 

Returns a list of people who have a file checked out. If the list is empty, no one has 
the file checked out. 

Arguments 

connect!' onData, remotePath, checkOutLi st, emai 1 AddressLi st, 
numCheckedOut 

• connect i onData is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• remotePa th is the fully qualified remote file or folder path to check to see how 
many users have it checked out. 

• checkOutLi st is a list of strings corresponding to the users who have the file 
checked out. Each user string cannot exceed a maximum length of 64 characters. 

• em a i 1 Address Li st is a list of strings corresponding to the users' email addresses. 
Each email address string cannot exceed a maximum length of 64 characters. 

• numCheckedOut is the number of people who have the file checked out. This is 
returned from GetNumCheckedOut ( ). 

Returns 

true if successful, fal se if not. 
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SGSJ3etErrorMessageLength() 

Description 

Returns the length of the DLL's current internal error message. This is used to 
allocate the buffer passed into theGetErrorMessageO function. This function 
should be called only if an API function returns f a 1 se or <0, indicating a failure 
of that API function. 

Arguments 

connect!' onDatd 

connect! on Da ta is a pointer to the agents data that was passed into 
Dreamweaver during the Connect ( ) call. 

Returns 

An integer representing the length of the error message. 

SCSJBetErrorMessageQ 

Description 

Returns the last error message. If you implement getErrorMessageO, 
Dreamweaver calls it each time one of your API functions returns fa 1 se. 

If a routine returns - 1 or fa 1 se, it indicates an error message should be available. 

Arguments 

connect!' onData, errorMsg, msgLength 

• connect!' on Da ta is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• errorMsg is a preallocated string for the DLL to fill in with the error message. 

• msgLength is the length of the errorMsg buffer passed in. 
Returns 

true if successful, fal se if not. 
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SGSJSetNGteCoimtQ 

Description 

Returns the number of Design Note keys for the specified remote file or folder 
path. If unsupported by the source control system, Dreamweaver gets this 
information from the companion Design Note (.mno) file. 

Arguments 

connecti onData, remotePath 

• connecti onData is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• remote Pa th is the fully qualified remote file or folder path that the DLL 
checks for the number of Design Notes attached to it. 

Returns 

An integer representing the number of Design Notes associated with this file. If 
the function returns < 0, Dreamweaver considers it an error and tries to retrieve 
the error message from the DLL, if supported. 

SCSJ3etMaxNoteLength{) 

Description 

Returns the length of the largest Design Note for the specified file or folder. If 
unsupported by the source control system, Dreamweaver gets this information 
from the companion Design Note (.mno) file. 

Arguments 

connectionData, remotePath 

• connecti onData is a pointer to the agents data that was passed into 
Dreamweaver during the Connect ( ) call. 

• remotePa th is the fully qualified remote file or folder path that the DLL 
checks for the maximum Design Note length. 

Returns 

An integer representing the size of the longest Design Note associated with this 
file. If the function returns < 0, Dreamweaver considers it an error and tries to 
retrieve the error message from the DLL, if supported. 
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SGSJBetDesignNotesQ 

Description 

Retrieves key-value pairs from the meta information for the specified file or folder. 
If unsupported by the source control system, Dreamweaver retrieves the 
information from the corresponding Design Note (.mno) file. 

Arguments 

connectionData, remotePath, keyList, valueList, showCol umnii st, 
noteCount, noteLength 

• connect!' onData is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• remotePa th is the fully qualified remote file or folder path that the DLL 
checks for the number of items. 

• keyList is a list of Design Note keys, such as "Status". 

• val ue Li st is a list of Design Note values corresponding to the Design Note 
keys, such as "Awaiting Signoff". 

• showCo 1 umnL is t is a list of Boolean values corresponding to the Design Note 
keys, which indicate whether Dreamweaver can display the key as a column in 
the Site window. 

• noteCount is the number of Design Notes attached to this file or folder; this 
value is returned by the Get NoteCount ( ) call. 

• noteLength is the maximum length of a Design Note; this is the value 
returned by the GetMaxNoteLength ( ) call. 

Returns 

true if successful, fal se if not. 
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SCSJSetDessgnNotesQ 

Description 

Stores the key-value pairs in the meta information for the specified file or folder. 
This replaces the set of meta information for the file. If unsupported by the source 
control system, Dreamweaver stores Design Notes in .mno files. 

Arguments 

connectionData, remotePath, keyList, valueList, showCol umnii st, 
noteCount, noteLength 

• connect!' onData is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• remotePa th is the fully qualified remote file or folder path that the DLL 
checks for the number of items. 

• keyList is a list of Design Note keys, such as "Status". 

• val ue Li st is a list of Design Note values corresponding to the Design Note 
keys, such as "Awaiting Signoff". 

• showCo 1 umnL is t is a list of Boolean values corresponding to the Design Note 
keys, which indicate whether Dreamweaver can display the key as a column in 
the Site window. 

• noteCount is the number of Design Notes attached to this file or folder; this 
lets the DLL know how big the specified lists are. If note Co unt is 0, all Design 
Notes are removed from the file. 

• noteLength is the length of the largest Design note for the specified file 
or folder. 

Returns 

true if successful, fal se if not. 
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SCSJsRemoteNewer() 

Description 

Checks each specified remote path to see if the remote copy is newer. If 
unsupported by the source control system, Dreamweaver uses its internal 
i sRemoteNewer algorithm. 

Arguments 

connectionData, remotePathii st, / ocal PathLi st, remotel sNewerLi st, 
numltems 

• connect!' onData is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• remotePa thList is a list of fully qualified remote file or folder paths to 
compare for newer status. 

• / ocal PathLi st is a mirrored list of fully qualified local file or folder paths. 

• remotelsNewerLi st is a list of integers, populated by the DLL to let 
Dreamweaver know which of the corresponding files is newer on the remote 
side. The following values are valid: 1 indicates the remote version is newer, -1 
indicates the local version is newer, 0 indicates the versions are the same. 

• numltems is the number of items in each list. 
Returns 

true if successful, false if not. 
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nabsers 



If the optional enablers are not supported by the source control system or the 
application is not connected to the server, then Dreamweaver determines when 
the menu items are enabled based on the information it has about the remote files. 

SCS^canConnect() 

Description 

Returns whether or not the Connect menu item should be enabled. 

Arguments 

None. 

Returns 

true if enabled, fal se if not. 

SCS^canGetC) 

Description 

Returns whether or not the Get menu item should be enabled. 
Arguments 

connectionData, remotePathii st, 7 ocal PathLI st, numltems 

• connect!' onData is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• remote Pa thList is a list of fully qualified remote file or folder paths to get. 

• 7 ocal Path Li st is a mirrored list of fully qualified local file or folder paths. 

• numltems is the number of items in each list. 
Returns 

true if enabled, f a 1 s e if no t . 



184 Chapter 18 



SGS^canCheckoutQ 

Description 

Returns whether or not the Checkout menu item should be enabled. 
Arguments 

connect!' onData, remotePathLi st, 1 ocal PathLi st, numltems 

• connect! on Data is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• remote Pa thList is a list of fully qualified remote file or folder paths to 
check out. 

• 7 ocal PathLi st is a mirrored list of fully qualified local file or folder paths. 

• numltems is the number of items in each list. 
Returns 

true if enabled, fal se if not. 

SCSjsanPiitQ 

Description 

Returns whether or not the Put menu item should be enabled. 
Arguments 

connect!' onData, 1 ocal PathLi st, remotePathLi st, numltems 

• connectionDa ta is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• 1 oca 1 PathLi st is a list of fully qualified local file or folder paths to put. 

• remote Pa thList is a mirrored list of fully qualified remote file or folder paths. 

• numltems is the number of items in each list. 
Returns 

true if enabled, fal se if not. 
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SCS^canChecksn{) 

Description 

Returns whether or not the Checkin menu item should be enabled. 
Arguments 

connecti onData, 1 ocal PathLi st, remotePathLi st, numltems 

• connecti onData is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• / ocal PathLi st is a list of fully qualified local file or folder paths to check in. 

• remotePa thiist is a mirrored list of fully qualified remote file or folder paths. 

• numltems is the number of items in each list. 
Returns 

true if enabled, f a 1 s e if no t . 

SCS^CanUndoCheckout(5 

Description 

Returns whether or not the Undo Checkout menu item should be enabled. 
Arguments 

connecti onData, remotePathLi st, 1 ocal PathLi st, numltems 

• connecti onData is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• remotePa thiist is a list of fully qualified remote file or folder paths to 
check out. 

• 7 ocal PathLi st is a list of fully qualified local file or folder paths to put. 

• numltems is the number of items in each list. 
Returns 

true if enabled, f a 1 s e if no t . 
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SCS^canNewFolderQ 

Description 

Returns whether or not the New Folder menu item should be enabled. 
Arguments 

connect!' onData, remotePath 

• connect! on Data is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• remote? a th is a fully qualified remote file or folder path that the user has 
selected to indicate where the new folder will be created. 

Returns 

true if enabled, f a 1 s e if no t . 

SCS^canDeleteQ 

Description 

Returns whether or not the Delete menu item should be enabled. 
Arguments 

connectionData, remotePathLi st 3 numl terns 

• connect! onData is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• remotePa thList is a list of fully qualified remote file or folder paths to delete. 

• numl terns is the number of items in each list. 
Returns 

true if enabled, f a 1 s e if no t . 

SCS^canRename() 

Description 

Returns whether or not the Rename menu item should be enabled. 
Arguments 

connect! onData, remotePathLi st 

• connect! onData is a pointer to the agent's data that was passed into 
Dreamweaver during the Connect ( ) call. 

• remotePa th is the fully qualified remote file or folder path that could 
be renamed. 

Returns 

true if enabled, fal se if not. 
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itemfnfo struct 



name 


char[256] 


name of file or folder 


isFolder 


bool 


true if folder, false if file 


month 


int 


month component of mod date 1-12 


day 


int 


day component of mod date 1-31 


year 


int 


year component of mod date 1900+ 


hour 


int 


hour component of mod date 0-23 


minutes 


int 


minute component of mod date 0-59 


seconds 


int 


second component of mod date 0-59 


type 


char[256] 


type of file (if not set by DLL, DW will use file 
extension to determine type, as it does now) 


size 


int 


in bytes 



SCS^BeforeGetQ 

Description 

Dreamweaver calls this function before getting or checking out one or more files. 
This enables your DLL to perform one operation, such as adding a checkout 
comment, to a group of files. 

Arguments 

*connectionData 

*connectionData is a pointer to the connection data. 
Returns 

A Boolean true if successful, fal se if unsuccessful. 
Example 

To get a group of files, Dreamweaver makes calls to the DLL in the 
following order: 

SCS_BeforeGet( connect i on Data ) ; 

SCS_Get (connect ion Da ta ,remotePath Li stl , local Pa th Li stl , success Li stl ) ; 
SCS_Get( connect ion Data , remotePathLi st2, local Path Li st2 , success Li st2) ; 
SCS_Get( connect ion Data , remotePathLi st3, local Path Li st3 , success Li st3) ; 
SCS_AfterGet( connect i on Data ) ; 
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SCSJSeforePutQ 

Description 

Dreamweaver calls this function before putting or checking in one or more files. 
This enables your DLL to perform one operation, such as adding a checkin 
comment, to a group of files. 

Arguments 

*connecti onData 

*connecti onData is a pointer to the connection data. 
Returns 

A Boolean true if successful, fal se if unsuccessful. 
Example 

To get a group of files, Dreamweaver makes calls to the DLL in the 
following order: 

SCS_Bef ore Put ( connect i onData ) ; 

SCS_Put(connectionData , local Path Li stl , remotePathLi stl , successLi stl ) ; 
SCS_Put (connecti onData ,1 oca 1 Path Li st2 , remotePathLi st2 , successLi st2) ; 
SCS_Put( connect i onData ,1 oca 1 Path Li st3 , remotePathLi st3 , successLi st3) ; 
SCS_AfterPut( connect!' onData ) ; 

SCS^AfterGefQ 

Description 

Dreamweaver calls this function after getting or checking out one or more files. 
This enables your DLL to perform any operation after a batch get or checkout, 
such as putting up a summary dialog box. 

Arguments 

*connecti onData 

*connecti onData is a pointer to the connection data. 
Returns 

A Boolean true if successful, fal se if unsuccessful. 
Example 

See example in "SCS_BeforeGetQ" on page 188. 
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SCSjMterPutQ 

Description 

Dreamweaver calls this function after putting or checking in one or more files. 
This enables the DLL to perform any operation after a batch put or checkin, such 
as putting up a summary dialog box. 

Arguments 

*connecti onData 

*connecti onData is a pointer to the connection data. 
Returns 

true if successful, fal se if unsuccessful. 
Example 

See example in "SCS_BeforePut()" on page 189. 
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CHAPTER 19 

C- Level Extensibility 



The C-level extensibility mechanism lets you implement Dreamweaver 
extensibility files using a combination of JavaScript and your own C code. 
You define functions using C, bundle them in a DLL or shared library save 
the library in the Configuration/JSExtensions folder within the Dreamweaver 
application folder, and then call the functions from JavaScript using the JavaScript 
interpreter built into Dreamweaver. 

For example, you may want to define a Dreamweaver object that inserts the 
contents of a user-specified file into the current document. Because client-side 
JavaScript does not provide support for file I/O, you must write a function in 
C to provide this functionality. 

You could use the following HTML and JavaScript to create a simple Insert Text 
from File object. Notice that the ob j ectTag ( ) function calls a C function named 
readContentsOf Fi 1 e( ), which is stored in a library named my Li bra ry. 

<HTML> 
<HEAD> 
<SCRIPT> 

functi on objectTag( ) { 

fileName = document . forms[0] .myFi 1 e . val ue ; 
return my Li bra ry . readContentsOf Fi 1 e( f i 1 eName ) ; 

} 

</SCRIPT> 
</HEAD> 

<B0DY> 
<F0RM> 

Enter the name of the file to be inserted: 
<INPUT TYPE="file" NAM E=" myFi 1 e"> 

</F0RM> 
</B0DY> 
</HTML> 



191 



The readContentsOfFileO function accepts a list of arguments from the 
user, unpacks the argument containing the file name, reads the contents of 
the file, and packages the contents of the file as the return value. For more 
information about the JavaScript data structures and functions that appear in 
readContentsOf Fi 1 e( ), see "The C-level extensibility API" on page 193. 

JSBool 

readContentsOf Fi 1 e(JSContext *cx, JSObject *obj , unsigned int -i 

argc, jsval *argv, jsval *rval ) 

{ 

char *fileName, *fi 1 eContents ; 
JSBool success; 
unsigned int length; 

/* Make sure caller passed in exactly one argument. If not, 

* then tell the interpreter to abort script execution. */ 
if (argc != 1){ 

JS_ReportError(cx , "Wrong number of arguments", 0); 
return JS_FALSE; 
} 

/* Convert the argument to a string */ 

fileName = JS_Val ueToStri ng( cx , argv[0], &length); 

if (fileName = NULL) { 

JS_ReportError(cx , "The argument must be a string", 0); 

return JS_FALSE; 

} 

/* Use the string (the file name) to open and read a file */ 
fileContents = exerci seLef tToTheReader ( f i 1 eName ) ; 

/* Store file contents in rval , which is the return value 

* passed 

* back to the cal 1 er */ 

success = JS_Stri ngToVal ue(cx , fileContents, 0, *rval); 
f ree(f i 1 eContents ) ; 

/* Return true to continue or false to abort the script */ 
return success; 

} 

To ensure that the readContentsOfFileO function executes as designed rather 
than causing a JavaScript error, you must register the function with the JavaScript 
interpreter by including a function called MM_I ni t ( ) in your library. When 
Dreamweaver loads the library at startup, it calls the MM_I ni t ( ) function to 
get three pieces of information: 

• The JavaScript name of the function 

• A pointer to the function 

• The number of arguments that the function expects 
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The MM_I n i t ( ) function for my Li b ra ry might look like this: 

voi d 

MM_Init( ) 
{ 

JS_Def i neFuncti on( " readContentsOf Fi 1 e" , rea dCon tents Of Fi 1 e , 

1); 
} 

Your library must include exactly one instance of the following macro: 

/* MM_STATE is a macro that expands to some definitions that are 

* needed to interact with Dreamweaver. This macro must 

* be defined exactly once in your library. */ 
MM_STATE 

Note: The library can be implemented in either Cor C++, but the file containing M M_ I n i t ( ) 
and MM_STATE must be implemented in C. The C++ compiler garbles function names, 
making it impossible for Dreamweaver to find the MM_I n i t ( ) function. 



The C-level extensibility API 

The C code in your library must interact with the Dreamweaver JavaScript 
interpreter at three different times: 

• At startup, to register the library's functions. 

• When the function is called, to unpack the arguments that are being passed 
from JavaScript to C. 

• Before the function returns, to package the return value. 

To accomplish these tasks, the interpreter defines several data types and exposes 
an API. Definitions for the data types and functions listed in this section appear 
in the file mm_jsapi.h. For your library to work properly, you must include 
mm_jsapi.h at the top of each file in your library with the following line: 

#i ncl ude "mm_jsapi . h" 

typedef struct JSContext JSContext 

Description 

A pointer to this opaque data type is passed to the C-level function. Some of the 
functions in the API accept this pointer as one of their arguments. 

typedef struct JSObject JSObject 

Description 

A pointer to this opaque data type is passed to the C-level function. This data type 
represents an object, which may be an array object or some other object type. 
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typedef struct jsval jsvaS 



Description 

An opaque data structure that can contain an integer, or a pointer to a float, 
string, or object. Some functions in the API can be used to read the values of 
function arguments by reading the contents of a j s va 1 , and some can be used to 
write the function s return value by writing a j s v a 1 . 

typedef enum { JS^FALSE = 0 f JSJTRUE ~ 1 } JSBool 

Description 

A simple data type used to store a Boolean value. 

typedef JSBool (*JSNative)(JSContext *cx ? JSObject *obj f 
unsigned int argc, jsvaS *argv, jsva! *rval) 

Description 

The function signature for C-level implementations of JavaScript 
functions, where: 

• cx is a pointer to an opaque JSContext structure, which must be passed to 
some of the functions in the JavaScript API. This variable holds the interpreter's 
execution context. 

• obj is a pointer to the object in whose context the script executes. While the 
script is running, the this keyword is equal to this object. 

• a rgc is the number of arguments being passed to the function. 

• a rg v is a pointer to an array of j s v a 1 s . The array is a r g c elements in length. 

• r va 1 is a pointer to a single j s va 1 . The function's return value should be 
written to *rval . 

The function returns JS_TRUE upon success or JS_FALSE upon failure. If 
JS_FALSE is returned, the current script stops executing. 

JSBooi JSJDefmeFuncticmC) 

Description 

Registers a C-level function with the JavaScript interpreter in Dreamweaver. After 
this function returns, JavaScript scripts that call the function specified in name will 
execute the code pointed to by ca 1 1 . 

Typically, this function is called from MM_Ini t( ), which Dreamweaver calls 
during startup. 
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Arguments 

char *name, JSNative call, unsigned int nargs 

• n a me is the name of the function as it is exposed to JavaScript. 

• ca 1 1 is a pointer to a C-level function. The function must accept the same 
arguments as readContentsOf Fi 1 e, and it must return a JSBool indicating 
success or failure. 

• nargs is the number of arguments that the function expects to receive. 
Returns 

A Boolean value indicating success (JS_TRUE) or failure (JS_FALSE). 

char *JSJVakjeToStrsng() 

Description 

Extracts a function argument from a j s va 1 , converts it to a string (if possible), 
and passes the converted value back to the caller. 

Arguments 

JSContext *cx, jsval v, unsigned int *pLength 

• cx is the opaque JSContext pointer that was passed to the JavaScript function. 

• v is the jsval from which the string is to be extracted. 

• p Length is a pointer to an unsigned integer. This function sets * p 1 e n g t h equal 
to the length of the string in bytes. 

Returns 

A pointer to a string on success or nul 1 on failure. 

JSBoo! JSJ^aiueTototegerQ 

Description 

Extracts a function argument from a j s va 1 , converts it to an integer (if possible), 
and passes the converted value back to the caller. 

Arguments 

JSContext *cx, jsval v, long *lp 

• cx is the opaque JSContext pointer that was passed to the JavaScript function. 

• v is the j s va 1 from which the string is to be extracted. 

• 1 p is a pointer to a 4-byte-long integer. This function stores the converted 
value in * 1 p . 

Returns 

A Boolean value indicating success (JS_TRUE) or failure (JS_FALSE). 
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JSBool JSJ/alueToDoiibleQ 

Description 

Extracts a function argument from a j s va 1 , converts it to a double (if possible), 
and passes the converted value back to the caller. 

Arguments 

JSContext *cx, jsval v, double *dp 

• cx is the opaque JSContext pointer that was passed to the JavaScript function. 

• v is the jsval from which the string is to be extracted. 

• dp is a pointer to an 8-byte double. This function stores the converted 
value in *dp. 

Returns 

A Boolean value indicating success (JS_TRUE) or failure (JS_FALSE). 

JSBool JS^Va!ueToBoo!ean() 

Description 

Extracts a function argument from a j s va 1 , converts it to a Boolean value (if 
possible), and passes the converted value back to the caller. 

Arguments 

JSContext *cx, jsval v, JSBool *bp 

• cx is the opaque JSContext pointer that was passed to the JavaScript function. 

• v is the jsval from which the string is to be extracted. 

• bp is a pointer to a JSBool . This function stores the converted value in *bp. 
Returns 

A Boolean value indicating success (JS_TRUE) or failure (JS_FALSE). 

JSBool JS_ValueToObject() 

Description 

Extracts a function argument from a j s va 1 , converts it to an object (if possible), 
and passes the converted value back to the caller. If the object is an array, use 
JS_GetArrayLength( ) and JS_GetEl ement ( ) to read its contents. 
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Arguments 

JSContext *cx, jsval v, JSObject **op 

• cx is the opaque JSContext pointer that was passed to the JavaScript function. 

• v is the jsval from which the string is to be extracted. 

• op is a pointer to a (JSOb j ect *). This function stores the converted value 
in *op. 

Returns 

A Boolean value indicating success (JS_TRUE) or failure (JS_FALSE). 

JSBoo! JS^StringToVaiueO 

Description 

Stores a string return value in a j s va 1 . 
Arguments 

JSContext *cx, char *bytes, size_t sz, jsval *vp 

• cx is the opaque JSContext pointer that was passed to the JavaScript function. 

• bytes is the string to be stored in the j s va 1 . The string data is copied, so the 
caller should free the string when it is no longer needed. If the string size is not 
specified (see the sz argument), then the string must be null- terminated. 

• sz is the size of the string, in bytes. If sz is 0, then the length of the 
null-terminated string is computed automatically. 

• i/p is a pointer to the j s va 1 into which the contents of the string should 
be copied. 

Returns 

A Boolean value indicating success (JS_TRUE) or failure (JS_FALSE). 

JSBool JS^DoubleToVa!ue() 

Description 

Stores a floating-point number return value in a j s va 1 . 
Arguments 

JSContext *cx, double dv, jsval *vp 

• cx is the opaque JSContext pointer that was passed to the JavaScript function. 

• d v is an 8-byte floating-point number. 

• vp is a pointer to the j s va 1 into which the contents of the double should 
be copied. 

Returns 

A Boolean value indicating success (JS_TRUE) or failure (JS_FALSE). 
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JSVal JS^BooleanToVaiue{) 

Description 

Stores a Boolean return value in a j s va 1 . 

Arguments 

JSBool bv 

Returns 

A JSVal containing the Boolean value passed in. 

JSVaS JSJntegerToVaiueQ 

Description 

Stores an integer return value in a j s va 1 . 

Arguments 

long Iv 

Returns 

A JSVal containing the integer passed in. 

JSVal JSJ3bjectToVaIue() 

Description 

Stores an object return value in a j s va 1 . Use JS_ NewArrayObjectOto create an 
array object; use JS_SetEl ement ( ) to define its contents. 

Arguments 

JSObject *obj 

Returns 

A JSVal containing the object passed in. 

char * JSJ3bjectType() 

Description 

Given an object reference, returns a string describing the type of the object. For 
array objects, the return value is Array. 

Arguments 

JSObject *obj 

Typically, this argument is passed in and converted using JS_Val ueToObject( ). 
Returns 

A pointer to a null-terminated string. The caller should not free this string when it 
has finished. 
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JSObject * JS^NewArrayObJectQ 

Description 

Creates a new object that contains an array of j s v a 1 s . 
Arguments 

JSContext *cx, unsigned int length, jsval *v 

• cx is the opaque JSContext pointer that was passed to the JavaScript function. 

• 7 eng th is the number of elements that the array will hold. 

• v is an optional pointer to the j s va 1 s to be stored in the array. If the return 
value is not null, v is an array containing / ength elements. If the return value 
is nul 1 , then the initial content of the array object is undefined (and may be set 
using JS_SetEl ement( )). 

Returns 

A pointer to a new array object, or nul 1 upon failure. 

long JSJBetArrayLengthQ 

Description 

Given a pointer to an array object, gets the number of elements in the array. 
Arguments 

JSContext *cx, JSObject *obj 

• cx is the opaque JSContext pointer that was passed to the JavaScript function. 

• obj is a reference to an array object. 
Returns 

The number of elements in the array, or -1 upon failure. 
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JSBool JSJ3etElement{) 

Description 

Reads a single element of an array object. 
Arguments 

JSContext *cx, JSObject *obj , unsigned int index, jsval *v 

• cx is the opaque JSContext pointer that was passed to the JavaScript function. 

• obj is a pointer to an array object. 

• index is an integer index into the array. The first element is index 0, and the 
last element is index (length - 1 ) . 

• v is a pointer to a j s v a 1 where the contents of the j s v a 1 in the array should 
be copied. 

Returns 

A Boolean value indicating success (JS_TRUE) or failure (JS_FALSE). 

JSBool JS ra SetElement() 

Description 

Writes a single element of an array object. 
Arguments 

JSContext *cx, JSObject *obj , unsigned int index, jsval *v 

• cx is the opaque JSContext pointer that was passed to the JavaScript function. 

• obj is a pointer to an array object. 

• index is an integer index into the array. The first element is index 0, and the 
last element is index (length - 1 ) . 

• v is a pointer to a j s va 1 whose contents should be copied to the j s va 1 in 
the array. 

Returns 

A Boolean value indicating success (JS_TRUE) or failure (JS_FALSE). 
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JSBool JSJExecuteScriptQ 

Description 

Compiles and executes a string of JavaScript. If the script generates a return value, 
it is returned in *rval . 

Arguments 

JSContext *cx, JSObject *obj , char ^script, unsigned in sz, 
jsval *rval 

• cx is the opaque JSContext pointer that was passed to the JavaScript function. 

• obj is a pointer to the object in whose context the script executes. While the 
script is running, the this keyword is equal to this object. Usually this is the 
JSObject pointer that was passed to the JavaScript function. 

• script is a string containing JavaScript code. If the string size is not specified 
(see the sz argument), then the string must be null-terminated. 

• sz is the size of the string, in bytes. If sz is 0, then the length of the null- 
terminated string is computed automatically. 

• r va 1 is a pointer to a single jsval. The function's return value is stored 
in *rval . 

Returns 

A Boolean value indicating success (JS_TRUE) or failure (JS_FALSE). 

JSBool JS„ReportError{) 

Description 

Describes the reason for a script error. Call this function before returning 
JS_FALSE to give the user information about why the script failed (for example, 
"wrong number of arguments"). 

Arguments 

JSContext *cx, char *error, size_t sz 

• cx is the opaque JSContext pointer that was passed to the JavaScript function. 

• error is a string containing the error message. The string is copied, so the caller 
should free the string when it is no longer needed. If the string size is not 
specified (see the sz argument, below), then the string must be null-terminated. 

• sz is the size of the string, in bytes. If sz is 0, then the length of the 
null-terminated string is computed automatically. 

Returns 

A Boolean value indicating success (JS_TRUE) or failure (JS_FALSE). 



O Level Extensibility 201 



Calling a C function from JavaScript 



Once you know how C-level extensibility works in Dreamweaver and the data 
types and functions it relies on, it's useful to walk through an example of how to 
build a library and call a function. 

This exercise requires three files, which are included in the Extending/ c_files 
folder inside the Dreamweaver application folder: 

• mm_jsapi.h is a header file that includes definitions for the data types and 
functions described in "The C-level extensibility API" on page 193. 

• Sample.c is an example file that defines the compute Sum( ) function. 

• Sample.mak is a makefile that you can use to build Sample.c into a DLL with 
Microsoft Visual C++; Sample.proj is the equivalent file for building a CFM 
Library with Metrowerks Code Warrior. If you are using another tool, you can 
create the makefile yourself. 

To build the DLL in Windows: 

1 In Microsoft Visual C++, choose File > Open Workspace and select 
Sample.mak. 

2 Choose Build > Rebuild All. 

When the build operation is complete, a file called Sample.dll appears in the 
folder containing Sample.mak (or one of its sub folders). 

To build the shared library on the Macintosh: 

1 Open Sample.proj in Metrowerks Code Warrior. 

2 Build the project to generate a CFM Library. 

When the build operation has finished, a file called Sample appears in the 
folder containing Sample.proj (or in one of its sub folders). 
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To call the computeSum() function from the Insert Horizontal Rule object: 

1 In the Configuration folder within the Dreamweaver application folder, create 
a folder called JSExtensions. 

2 Copy Sample.dll (Windows) or Sample (Macintosh) to the JSExtensions folder. 

3 In a text editor, open the file called horizontal_rule.htm that resides in the 
Configuration/ Objects/ Common folder. 

4 Add the line alert (Sample. computeSum(2,2) ) ; to the objectTag( ) 
function so that it appears as follows: 

functi on objectTag( ) { 

// Return the html tag that should be inserted 
al ert( Sampl e . computeSum( 2 , 2 ) ) ; 
return "<HR>"; 

} 

5 Save the file and restart Dreamweaver. 
To execute the computeSum() function: 

Choose Insert > Horizontal Rule. A dialog box containing the number 4 — the 
result of computing the sum of 2 plus 2 — appears. 
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The Dreamweaver JavaScript API 



The objects, properties, and especially the methods described in "The Document 
Object Model and JavaScript" on page 13 are a good foundation on which 
to build extensibility into Dreamweaver. Several tasks unique to authoring 
environments cannot be accomplished with the methods available in the 
Netscape, Microsoft, or W3C DOMs, however. The most obvious example 
of this is selection, which is integral to the user experience in an authoring 
environment: DOM Level 1 and the proprietary browser DOMs do not address 
selection because users cannot select and modify content (except in form fields) 
in a browser window. 

To make creating useful Dreamweaver extensions and customizing Dreamweaver 
menus possible, Dreamweaver exposes more than 400 JavaScript functions to 
developers beyond the standards-based DOM methods. This represents a huge 
expansion over what was available in Dreamweaver 3- Almost any task that the 
user can accomplish in Dreamweaver with the menus, floating panels, inspectors, 
Site window, or Document window can now be done with JavaScript. 
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Understanding the objects in the API 



All of the custom functions in the following sections are methods of 
the dreamweaver object, the si te object, or the object that represents a 
document's DOM. Methods that fit into the latter category are listed here as 
dotn . fundi on Name (). To produce the desired results, you must first get the 
DOM of a document and call the functions as methods of that DOM. You 
cannot simply type dom. fundi onName( ). For example: 

var currentDOM = dreamweaver . getDocumentDOM( ' document ') ; 
currentDOM. setSelecti on (100, 200 ) ; 
currentDOM . cl i pCopy ( ) ; 
var otherDOM = 

dreamweaver . openDocument( dreamweaver . get Si teRoot( )-< 
+ "html/foo.htm"); 
otherDOM . endOf Document ( ) ; 
otherDOM. cl ipPaste( ) ; 

Unless otherwise noted, methods of the dom object can operate only on open 
documents, and running a function on a document that isn't open will cause 
Dreamweaver to report an error. Methods of the dom object that can operate 
only on the active document or on closed documents indicate this fact in 
their descriptions. 

In Dreamweaver 4, dw is synonymous with d reamwea ver. Thus all of the methods 
of the dreamweaver object can be referred to as dw . fundi onNamei ). This 
notation appears in code examples throughout this and other chapters. 

About enablers 

Because every menu item in Dreamweaver is implemented as a JavaScript 
function, a JavaScript mechanism is required to determine when menu items 
should be enabled. This mechanism is a series of functions called enablers. 

An enabler determines whether its associated main function can operate in the 
current context. For example, si te . canGet( ) determines whether Dreamweaver 
can perform a Get operation (site.getO). 

Each function specification in this API lists the enabler for the function, if 
applicable. (Some functions do not have enablers, either because the menu 
item associated with the function is always enabled, or because the function is 
unrelated to menus.) For function specifications for the enablers, see "Enablers" 
on page 465. 

How this chapter is organized 

The methods in the Dreamweaver JavaScript API are grouped functionally and 
then alphabetically by object and then by method name. For example, methods 
that deal with creating, applying, and deleting CSS styles are grouped under CSS 
Style functions; methods of the dom object are listed first, followed by methods of 
the dreamweaver object. Deprecated functions and enablers are listed at the end 
of this chapter. Optional arguments are enclosed in braces ({ }). 
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Getting document data through the DOM 



Virtually all of the functions involved in DOM manipulations require 
that you first determine which DOM to change. This is the task of 
dreamweaver . getDocumentDOM( ), and thus it is the most important function. 

dreamweaver 0 getDocumentDOy{) 

Availability 

Dreamweaver 2.0 

Description 

Provides access to the tree of objects for the specified document. After the tree of 
objects is returned to the caller, the caller can edit the tree to change the contents 
of the document. 

Arguments 

sourceDoc 

sourceDoc must be "document", "parent", "pa rent . frames [ number'] ", 
"parent . frames [ ' frameName' ] ", or a URL. document specifies the 
document that has the focus and contains the current selection, parent 
specifies the parent frameset (if the currently selected document is in a frame), 
and parent, frames [number] and parent, frames [ ' frameName' ] specify a 
document that is in a particular frame within the frameset containing the current 
document. If the argument is a relative URL, it is relative to the extension file. 
In Dreamweaver 4, sourceDoc defaults to document if omitted. 

Note: If the argument is "document", the caller must be appl yBeha vi or ( ) , 

del eteBehavi or( ), objectTag( ), or any function in a command or Property Inspector 

file in order to perform edits to the document. 

Returns 

The JavaScript document object at the root of the tree. 

Enabler 

None. 

Example 

The following code snippet uses dreamweaver . getDocumentDOM ( ) to access the 
background color of the current document: 

var theDOM = dreamweaver . getDocumentDOM( "document ") ; 
theDOM. body. bgcolor = "#000000"; 
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Assets panel functions 

Assets panel functions (programmed into the API as "asset palette") let you 
manage and use the elements shown in the Assets panel (these can be templates, 
libraries, images, Shockwave and Flash movies, URLs, colors, movies, and scripts). 



dreamweaver 0 assetPaIette 0 addToFavor§tesFromDocument() 

Availability 

Dreamweaver 4.0 

Description 

Adds the element selected in the Document window to the Favorites list. This 
function handles only images, movies, Shockwave files, Flash files, text font colors, 
and URLs. 

Arguments 

None. 

Returns 

Nothing. 



drearnweavef\assetPaIette,addToFavorstesFromSjteAssets() 

Availability 

Dreamweaver 4.0 

Description 

Adds elements selected in the Site list to the Favorites list and gives each item a 
nickname in the Favorites list. This function does not remove the element from 
the Site list. 



Arguments 

None. 

Returns 

Nothing. 
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dreamweaver D assetPalette,addToFavor§tesFromS3teW§ndow() 

Availability 

Dreamweaver 4.0 

Description 

Adds the elements selected in the Site window or site map to the Favorites list. 
This function handles only images, movies, scripts, Shockwave files, Flash files, 
and URLs (in the case of the site map). If other folders or files are selected, they 
are ignored. 

Arguments 

None. 

Returns 

Nothing. 

dreamweaver,assetPaIeffe,copyToSBte() 

Availability 

Dreamweaver 4.0 

Description 

Copies selected elements to another site and puts them in that site's Favorites list. 
If the elements are files (other than colors or URLs), the actual file is copied into 
that site. 

Arguments 

targetSite 

targetSi te is the name of the target site, as returned from the 
si te . getSi tes( ) call. 

Returns 

Nothing. 
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dreamweaver.assetFaSette.edstQ 

Availability 

Dreamweaver 4.0 

Description 

Edits selected elements with primary external editor or Custom Edit control. For 
colors, trie color picker appears. For URLs, a dialog box appears prompting the 
user for a URL and a nickname. Not available for the site list of colors and URLs. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamweaver . asset Pal ette.canEditO 



dreamweaver.assetPalette.getSeiectedCategoryO 

Availability 

D ream weaver 4 . 0 

Description 

Returns the currently selected category, which can be one of the following: 

"templates", "library", "images", "movies", "Shockwave", "flash", 
"scri pts", "col ors", or "url s". 

Arguments 

None. 

Returns 

The currently selected category. 
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dreamweaver.asse!PaSette,getSelected!tems() 

Availability 

Dreamweaver 4.0 

Description 

Returns an array of the selected items in the Assets panel, either in the site list or 
Favorites list. 

Arguments 

None. 

Returns 

An array of three strings for each selected item: 

• name is the name/file name or nickname as seen in the panel. 

• value is the full file path, full URL, or color value depending on the 
item selected. 

• type is either "fol der" or one of the categories: "templates", "library", 
"images", "movies", "Shockwave", "flash", "scripts", "colors", or 
"url s". 

Note: If nothing is selected in the Assets panel, this function returns an array of one 
empty string. 

Example 

If "URLs" is the category, and a folder "MyFolderName" and a URL 
"MyFavoriteURL" are both selected in the Favorites list, the function will return: 

items[0] = "MyFolderName" 

i terns [1] = " " 

items[2] = "folder" 

items[3] = "MyFavoriteURL" 

items[4] = "http://www.MyFavoriteURL.com" 

items [5] = "urls" 

dreamweaver u assetPaIette.getSelecfed¥3ew{) 

Availability 

Dreamweaver 4.0 

Description 

Indicates which list is currently shown in the Assets panel. 

Arguments 

None. 

Returns 

Returns either "site" or "favorites". 
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dreamweaver.assetPaSetteJnsertOrAppSyO 

Availability 

Dreamweaver 4.0 

Description 

Inserts selected elements or applies the element to the current selection. Applies 
templates, applies colors to selection, applies URLs to selection, and inserts URLs 
and other elements at the insertion point. If a document isn't open, the function is 
not available. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamweaver . asset Pal ette .canEdi t( ) 



dreamweaver D assetPa§etteJocate!nS^te() 

Availability 

Dreamweaver 4.0 

Description 

Selects files associated with the selected elements in the local side of the Site 
window. This function does not work for colors or URLs. Available in both the 
site list and the Favorites list. If a folder is selected in the Favorites list, it will 
be ignored. 

Arguments 

None. 

Returns 

Nothing. 
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dreamweaver.assetFaSette.newAssetQ 



Availability 

Dreamweaver 4.0 

Description 

Creates new element for the current category in the Favorites list. For library and 
templates, this is a new blank library or template file that the user can name 
immediately. For colors, the color picker appears. For URLs, a dialog box appears 
prompting the user for a URL and a nickname. Not available for images, movies, 
Shockwave files, Flash files, or scripts. 

Arguments 

None. 

Returns 

Nothing. 

dreamweaver.assetPaSette,newFolder() 

Availability 

Dreamweaver 4.0 

Description 

Creates a new folder in the current category with the default name (untitled) and 
puts an edit box around the default name. Only available in the Favorites list. 

Arguments 

None. 

Returns 

Nothing. 

dreamweaver.assetPaIette,recreateLsbraryFromDocument() 

Availability 

Dreamweaver 4.0 

Description 

Replaces the deprecated libraryPalette function, 

recreate Li bra ryFromDocument ( ). Creates an LBI file for the selected instance 
of a library item in the current document. This function is equivalent to clicking 
Recreate in the Property inspector. 

Arguments 

None. 

Returns 

Nothing. 
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dreamweaver.asse!PaSette,refreshS§teAssets() 



Availability 

Dreamweaver 4.0 

Description 

Scans site, switches to the site list, and populates the list. 

Arguments 

None. 

Returns 

Nothing. 

dr8amweaver.assetPaIette,removeFromFavor[tes() 

Availability 

Dreamweaver 4.0 

Description 

Removes the selected elements from the Favorites list. This function does not 
delete the actual file on disk, except in the case of a library or template where the 
user is prompted before the file is deleted. Only works in the Favorites list or if the 
category is "Library" or "Templates". 

Arguments 

None. 

Returns 

Nothing. 

dreamweaver 0 assetPa!ettejenameNickname() 

Availability 

Dreamweaver 4.0 

Description 

Edits the folder name or the files nickname by displaying an edit box around 
the existing nickname. Only available in the Favorites list or in the Library or 
Template category. 

Arguments 

None. 

Returns 

Nothing. 
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dreamweaver.assetPaSette,setSeiecteclCategory{) 

Availability 

Dreamweaver 4.0 

Description 

Switches to show a different category. 

Arguments 

categoryType 

categoryType can be one of the following categories: "tempi ates", "1 i brary", 
"images", "movies", "Shockwave", "flash", "scripts", "col ors", or 
"url s". 

Returns 

Nothing. 

dreamweaver B assetPaSette,setSe!ectedView{) 

Availability 

Dreamweaver 4.0 

Description 

Switches the display to show either the site list or Favorites list. 

Arguments 

viewType 

viewType can be si te or favori tes. 

Returns 

Nothing. 

dreamweaver 0 referencePaSette,getFontS[ze() 

Availability 

Dreamweaver 4.0 

Description 

Returns the current font size of the Reference panel display region. 

Arguments 

None. 

Returns 

The relative font size as sma 1 1 , medi urn, or 1 a rge. 
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dreamweaver.referencePaIette 0 setFontS[ze() 

Availability 

Dreamweaver 4.0 

Description 

Changes the font size displayed in the Reference panel. 

Arguments 

fonts ize 

f ontSi ze is one of the following relative sizes: smal 1 , medi urn, or large. 

Returns 

Nothing. 

Behavior functions 

Behavior functions let you add behaviors to and remove behaviors from an 
object, find out which behaviors are attached to an object, get information 
about the object to which a behavior is attached, and so on. Methods of the 
dreamweaver .behaviorlnspector object either control or act on the selection 
in the Behaviors panel, not in the current document. 

dom.addBehaviorQ 

Availability 

Dreamweaver 3.0 

Description 

Adds a new event/ action pair to the selected element. This function is valid only 
for the active document. 

Arguments 

event, action, (eventBasedlndex} 

• event is the JavaScript event handler that should be used to attach the behavior 
to the element; for example, onCl i ck, onMouseOver, or onLoad. 

• action is the function call that would be returned byapplyBehaviorO if the 
action were added using the Behaviors panel, for example, 

"MM_popupMsg( ' Hel 1 o World')". 

• eventBasedlndex is the position at which this action should be added. 
eventBasedlndex is a zero-based index; if two actions already are associated 
with the specified event, and you specify eventBasedlndex as 1, this action 
will be executed between the other two. If this argument is omitted, the action 
is added after all existing actions for the specified event. 
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Returns 

Nothing. 

Enabler 

None. 

dom,getBehav3or() 

Availability 

Dreamweaver 3.0 

Description 

Gets the action at the specified position within the specified event. This function 
acts on the current selection and is valid only for the active document. 

Arguments 

event, {eventBased Index} 

• event is the JavaScript event handler through which the action is attached to 
the element; for example, onCl i ck, onMouseOver, or onLoad. 

• eventBasedlndex is the position of the action to get. For example, if two 
actions are associated with the specified event, 0 is the first one and 1 is the 
second. If this argument is omitted, all the actions for the specified event 
are returned. 

Returns 

A string representing the function call (for example, 

"MM_swapImage( 'document. Imager , 'document. Imager , ' foo.gif ' , '#933 
292969950' ) "), or an array of strings if eventBased I ndex was omitted. 

Enabler 

None. 
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dom.reapplyBehavsorsQ 



Availability 

Dreamweaver 3.0 

Description 

Checks to make sure that the functions associated with any behavior calls on 
the specified node are in the HEAD of the document, and inserts them if 
they are missing. 

Arguments 

{el efnentNode) 

e 1 emen t Node is an element node within the current document. If the argument is 
omitted, Dreamweaver checks all element nodes in the document for orphaned 
behavior calls. 

Returns 

Nothing. 

Enabler 

None. 

dofY^removeBehavior() 

Availability 

Dreamweaver 3.0 

Description 

Removes the action at the specified position within the specified event. This 
function acts on the current selection and is valid only for the active document. 

Arguments 

event, {eventBasedlndex} 

• e ven t is the event handler through which the action is attached to the element; 
for example, onCl ick, onMouseOver, or on Load. If this argument is omitted, 
all actions are removed from the element. 

• eventBasedlndex is the position of the action to be removed. For example, 
if two actions are associated with the specified event, 0 is the first one and 

1 is the second. If this argument is omitted, all the actions for the specified 
event are removed. 

Returns 

Nothing. 

Enabler 

None. 
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dreamweaver.gefBehaviorElementQ 



Availability 

Dreamweaver 2.0 

Description 

Gets the DOM object corresponding to the tag to which the behavior is being 
applied. This function is applicable only in Behavior action files. 

Arguments 

None. 

Returns 

A DOM object or nul 1 . This function returns null under the following 
circumstances: 

• When the current script is not executing within the context of the 
Behaviors panel. 

• When the Behaviors panel is being used to edit a behavior in a timeline. 

• When the currently executing script was invoked by 

dreamweaver . pop up Ac ti on( ). 

• When the Behaviors panel is attaching an event to a link wrapper and the link 
wrapper does not yet exist. 

• When this function appears outside of an action file. 

Enabler 

None. 

Example 

dreamweaver . getBehavi or El ement( ) can be used in the same way as 
dreamweaver . getBehavi orTag( ) to determine whether the selected action is 
appropriate for the selected HTML tag, except that it gives you access to more 
information about the tag and its attributes. For example, if you write an action 
that can be applied only to a hyperlink (A HREF) that does not target another 
frame or window, you can use getBehavi orEl ement ( ) as part of the function 
that initializes the user interface for the Parameters dialog box: 

function ini tial izeUI ( ) { 

var theTag = dreamweaver . getBehavi or El ement () ; 
var CAN BEAPPLIED = ( theTag . tagName == "A" && - 
theTag. getAttri bute( "HREF" ) != null && - 
theTag. getAttri bute( "TARGET") == null); 
if ( CANBEAPPLI ED ) { 

// display the action UI 
} else{ 

// display a helpful message that tells the user 
// that this action can only be applied to a 
// hyperlink without an explicit target] 

} 
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dreamweaver.gefBehaviorTagQ 

Availability 

D ream weaver 1 . 2 

Description 

Gets the source of the tag to which the behavior is being applied. This function is 
applicable only in action files. 

Arguments 

None. 

Returns 

A string representing the source of the tag. This is the same string that is passed as 
an argument (HTM Le 1 erne nt) to the canAcceptBeha vi or ( ) function. If this 
function appears outside of an action file, the return value is an empty string. 

Enabler 

None. 

Example 

If you write an action that can be applied only to a hyperlink (A HREF), you can 
use getBeha vi orTag ( ) as part of the function that initializes the user interface 
for the Parameters dialog box: 

function Ini tial izeUI ( ) { 

var theTag = dreamweaver . getBehavi orTag( ) . tollpperCase( ) ; 
var CANBEAPPLI ED = ( theTag . i ndexOf( ' HREF ' ) != -1)); 
if ( CANBEAPPLI ED ) { 

// display the action UI 
} else{ 

// display a helpful message that tells the user 
// that this action can only be applied to a 
// hyperlink 

} 
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dreamweaver.pGpupActionQ 



Availability 

Dreamweaver 2.0 

Description 

Presents the user with a Parameters dialog box for the specified behavior action. To 
the user, the effect is the same as selecting the action from the Actions pop-up 
menu in the Behaviors panel. This function lets extension files other than actions 
attach behaviors to objects in the users document. It blocks other edits until the 
user dismisses the dialog box. 

Note: This function can be called only within ob jectTag( ) or in any script in a command 
or Property Inspector file. 

Arguments 

actionName, {funcCall} 

• acti on Name is the name of a file in the Configuration/Behaviors/Actions folder 
that contains a JavaScript behavior action (for example, "Ti mel i ne/ PI ay 
Timel i ne . htm"). 

• funcCa 1 / is a string containing a function call for the action specified in 
acti onName (for example, "MM_pl ayTi mel ine( . . . ) ")• This argument, if 
specified, is supplied by the appl yBeha vi or ( ) function in the action file. 

Returns 

The function call for the behavior action. When the user clicks OK in the 
Parameters dialog box, the behavior is added to the current document (the 
appropriate functions are added to the HEAD of the document, HTML may be 
added to the top of the BODY, and other edits may be made to the document). 
The function call (for example, "MM_pl ayTi mel i ne( . . . ) ") is not added to 
document, but becomes the return value of this function. 

Enabler 

None. 
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dreamweaver.behaviodnspector.getBehaviorAtO 



Availability 

Dreamweaver 3.0 

Description 

Gets the event/action pair at the specified position in the Behaviors panel. 

Arguments 

posi ti on Index 

Returns 

An array of two items: 

• An event handler 

• A function call or JavaScript statement 

Enabler 

None. 

Example 

Because positionlndex is a zero-based index, if the Behaviors panel displays 
the list shown, a call to dw. behavi orlnspector . getBehavi orAt(2) 
returns an array containing two strings: "onMouseOver" and 
"MM_changeProp( ' document . moon ' , ' document . moon ' , 
' src' , ' sun.gif 1 , ' IMG' )". 

dreamweaver n behav{'os1nspector n getBehaviorCount() 

Availability 

Dreamweaver 3.0 

Description 

Counts the number of actions attached to the currently selected element through 
event handlers. 

Arguments 

None. 

Returns 

An integer representing the number of actions attached to the element. This 
number is equivalent to the number of actions visible in the Behaviors panel 
and includes both Dreamweaver behavior actions and custom JavaScript. 

Enabler 

None. 
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Example 



A call to dw. behavi or Inspector . get Be ha vi orCounK ) for the selected link < A 
H RE F=" javascri pt : setCooki e( ) " on CI i ck="MM_popupMsg( ' A cookie has 
been set . ' ) ; pa rent . ri ghtf rame . 1 ocati on . href=' aftercooki e . html ' "> 
would return 2. 

dreamweaver,behavioHnspector,getSelectedBehavaor(5 

Availability 

Dreamweaver 3-0 

Description 

Gets the position in the Behaviors panel of the selected action. 

Arguments 

None. 

Returns 

An integer representing the position in the Behaviors panel of the selected action, 
or -1 if no action is selected. 

Enabler 

None. 

Example 

If the first action in the Behaviors panel is selected, as shown, a call to 

dw. behavi or Inspector . getSel ected Behavi or ( ) returns 0. 





;, ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^x^ ' 
Ev r ',r |x .'^ly;: 
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dreamweaver.behavioHnspector.moveBehav[orDown() 

Availability 

Dreamweaver 3.0 

Description 

Moves a behavior action lower in sequence by changing its execution order within 
the scope of an event. 

Arguments 

posi ti onlndex 

pos i 1 ion Index is the position of the action in the Behaviors panel. The first 
action in the list is at position 0. 

Returns 

Nothing. 

Enabler 

None. 

Example 

Assuming the Behaviors panel setup shown in this example, calling 
dw. behavi orlnspector . moveBehavi orDown(2) would swap the positions of 
the Custom Script and the Change Property actions ontheonMouseOver event. 
Calling dw. behavi orlnspector .moveBehavi orDown( ) for any other position 
would have no effect because the on CI i ck and onMouseOut events each have only 
one behavior associated with them, and the behavior at position 3 is already at the 
bottom of the onMouseOver group. 




onMouseOut Change Property 

onMouseOuer Change Property 

onMouseOuer Custom Script: alert('hi') 
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dreamweaver.behavioHnspector.moveBehavforUpO 



Availability 

Dreamweaver 3.0 

Description 

Moves a behavior higher in sequence by changing its execution order within the 
scope of an event. 

Arguments 

posi ti onlndex 

pos i 1 ion Index is the position of the action in the Behaviors panel. The first 
action in the list is at position 0. 

Returns 

Nothing. 

Enabler 

None. 

Example 

Assuming the Behaviors panel setup shown in this example, calling 
dw. behavi orlnspector .moveBehavi orUp(3) would swap the positions of the 
Custom Script and the Change Property actions ontheonMouseOver event. 
Calling dw. behavi orlnspector .moveBehavi orUp( ) for any other position 
would have no effect because the on CI i ck and onMouseOut events each have only 
one behavior associated with them, and the behavior at position 2 is already at the 
top of the onMouseOver group. 




onMouseOut Change Property 

onMouseOuer Change Property 

onMouseOuer Custom Script: alert('hi') 
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dreamweaver.behaviodnspector.setSeSectedBehavgorO 

Availability 

Dreamweaver 3.0 

Description 

Selects the action at the specified position in the Behaviors panel. 

Arguments 

posi ti on Index 

pos i 1 ion Index is the position of the action in the Behaviors panel. The 
first action in the list is at position 0. To deselect all actions, specify a 
posit ion Index of-1. Specifying a position for which no action exists 
is equivalent to specifying -1. 

Returns 

Nothing. 

Enabler 

None. 

Example 

Assuming the Behaviors panel setup shown in this example, calling 
dw. behavi or Inspector . setSel ectionO) would select the Change 
Property action associated with theonMouseOut event. 
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Clipboard functions 

Clipboard functions are all related to cutting, copying, and pasting. On the 
Macintosh, some clipboard functions can also apply to edit fields in dialog boxes 
and floating panels. Functions that can operate in edit fields are implemented 
both as methods of the dreamweaver object and as methods of the dom object. 
The d reamwea ver version of the function operates on the selection in the window 
that has focus: the current Document window, the Code inspector, or the Site 
window. On the Macintosh, the function can also operate on the selection in an 
edit field if the field has focus. The dom version of the function always operates on 
the selection in the specified document. 

domxHpCopyQ 

Availability 

Dreamweaver 3.0 

Description 

Copies the selection, including any HTML markup that defines the selection, to 
the clipboard. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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dom,dipCopyText() 

Availability 

Dreamweaver 3.0 

Description 

Copies the selected text to the clipboard, ignoring any HTML markup. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dom . can CI i pCopyText ( ) 
domxHpCutQ 

Availability 

Dreamweaver 3.0 

Description 

Removes the selection, including any HTML markup that defines the selection, 
to the clipboard. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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dom.clipPasteQ 



Availability 

Dreamweaver 3.0 

Description 

Pastes the contents of the clipboard into the current document at the current 
insertion point or in place of the current selection. If the clipboard contains 
HTML, it is interpreted as such. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dom . canCl i pPaste( ) 
Example 

If the clipboard contains <code> return true ; </code>, a call to 
dw. getDocumentDOM( ) . cl i pPaste( ) would result in the following: 
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dom.cHpFasteTextQ 

Availability 

Dreamweaver 3.0 

Description 

Pastes the contents of the clipboard into the current document at the current 
insertion point or in place of the current selection, replacing any linefeeds in 
the clipboard content with B R tags. If the clipboard contains HTML, it is not 
interpreted; angle brackets are pasted as &1 1 ; and &gt ; . 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dotn.canCl ipPasteText( ) 
Example 

If the clipboard contains <code>return true ; </code>, a call to 
dw.getDocumentDOM( ) . cl i pPasteText( ) would result in the following: 

u?»fe_ ...JAiM"!? 

: < code > return true; < /code >| :j|>g| Paste as Text 

HTML Source | 

: v • ■ E:--.terri.jl Editor . v |~1 'Wrzp ■ Q 
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! II asa^i jgSK 
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dreamweaver.cHpCopyQ 



Availability 

Dreamweaver 3.0 

Description 

Copies the current selection (from whichever Document window, dialog box, 
floating panel, or Site window pane has focus) to the clipboard. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamweaver . canCl i pCopy ( ) 
dreamweaver.clipCutQ 

Availability 

D ream weaver 3 . 0 

Description 

Removes the selection (from whichever Document window, dialog box, floating 
panel, or Site window pane has focus) to the clipboard. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamweaver . canCl i pCut( ) 
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dreamweaver.cHpFasteQ 

Availability 

Dreamweaver 3.0 

Description 

Pastes the contents of the clipboard into the current document, dialog box, 
floating panel, or Site window pane. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamweaver . canCl i p Paste ( ) 



dreamweaver.getCHpboardlextO 

Availability 

D ream weaver 3 • 0 

Description 

Gets all the text that is stored on the clipboard. 

Arguments 

[bAsText] 

[bAsText] is a Boolean value that specifies whether or not the clipboard content 
is retrieved as text. If bAs Text is true, the clipboard content is retrieved as text. If 
bAsText is f a 1 se, the behavior is the same as in Dreamweaver 3- This argument 
defaults to fa 1 se. 

Returns 

A string containing the contents of the clipboard, if the clipboard contains text 
(which may be HTML); otherwise, nothing. 

Enabler 

None. 

Example 

If dw. getCl i pboardText( ) returns "text <b>bold</b> text", then 
dw. getCl i pboardText( true) returns "text bold text". 
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Command functions 



Command functions help you make the most of the files in the Configuration/ 
Commands folder. They manage the Command menu and call commands from 
other types of extension files. 

dreamweaver 0 editCommandUst{) 

Availability 

Dreamweaver 3-0 

Description 

Opens the Edit Command List dialog box. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

dreamweaverjunCommandQ 

Availability 

Dreamweaver 3.0 

Description 

Executes the specified command. To the user, the effect is the same as choosing 
the command from a menu; if a dialog box is associated with the command, it 
appears (and the command script blocks other edits until the user dismisses the 
dialog box). This function provides the ability to call a command from another 
extension file. 

Note: This function can be called only within the objectTag( ) function or in any script in 
a command, Property Inspector file, or menu. 

Arguments 

commandFi 1 e, (commandArgl }, {commandArg2} ) ...{commandArgN} 

• command Fi le is the name of a file in the Configuration/ Commands folder. 

• The second and remaining arguments are passed to command Fi 1 e 
as arguments. 

Returns 

Nothing. 
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Enabler 



None. 
Example 

You can write a custom Property inspector for tables that lets users get to the 
Format Table command from a button on the inspector by calling the following 
function from the buttons on CI i ck event handler: 

function cal 1 FormatTabl e( ) { 

dw. r un Comma nd( ' Format Tabl e. htm' ) ; 

} 



Conversion functions 

Conversion functions deal with converting tables to layers, layers to tables, and 
Cascading Style Sheets (CSS) styles to HTML markup. Each function exactly 
duplicates the behavior of one of the conversion commands in the File or 
Modify menu. 



dornxonvertLayersToTableQ 

Availability 

D ream weaver 3 . 0 

Description 

Opens the Convert Layers to Table dialog box. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dom . can Con vert Lay ersToTabl e( ) 
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domxonvertTablesToLayersQ 

Availability 

Dreamweaver 3.0 

Description 

Opens the Convert Tables to Layers dialog box. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dom . canConvertTabl esTo Layers ( ) 

dom,convertTo30() 

Availability 

Dreamweaver 3.0 

Description 

Opens the Convert to 3.0 Compatible dialog box. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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CSS style functions 

CSS style functions handle the application, removal, creation, and deletion of 
CSS styles. Methods ofthe dreamweaver . cssStyl ePal ette object either control 
or act on the selection in the Style panel, not in the current document. 

dom.appfyCSSStyleQ 

Availability 

Dreamweaver 4.0 

Description 

Applies the specified style to the specified element. This function is valid only for 
the active document. 

Arguments 

el ementNode, styleName, [cl assOrlD], [bForceNesti ng] 

• e 7 emen tNode is an element node in the DOM. If e 1 emen tNode is specified as 
NULL or empty string ( ' ' ), the function acts on the current selection. 

• styl eNdme is the name of a CSS style. 

• [c 1 a ss Or ID ] is the attribute with which the style should be applied (either 
"class" or "id"). If el ementNode is specified as NU LL or empty string and no tag 
exactly surrounds the selection, the style is applied using SPAN tags. If the 
selection is an insertion point, Dreamweaver uses heuristics to determine to 
which tag the style should be applied. 

• [bForceNes t ing] is a Boolean value, which indicates whether or not nesting is 
allowed. If the bForceNes t ing flag is specified, Dreamweaver inserts a new 
SPAN tag instead of trying to modify the existing tags in the document. This 
argument defaults to f al se if not specified. 

Returns 

Nothing. 

Enabler 

None. 

Example 

The following code applies the red style to the selection, either by surrounding 
the selection with SPAN tags or by applying a CLASS attribute to the tag that 
surrounds the selection: 

var theDOM = dreamweaver . getDocumentDOM( ' document ') ; 
theDOM.applyCSSStyle( " , ' red' ) ; 
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dom.removeCSSStyle(5 

Availability 

Dreamweaver 3.0 

Description 

Removes the CLASS or I D attribute from the specified element, or removes the 
SPAN tag that completely surrounds the specified element. This function is valid 
only for the active document. 

Arguments 

el ementNode, {classOrlD} 

• e 1 emen tNode is an element node in the DOM. If e 7 ementNode is specified as 
an empty string ( ' ' ), the function acts on the current selection. 

• c 1 assOrlD is the attribute that should be removed (either "class" or "id"). If 
cl assOrlD is not specified, it defaults to "cl ass". If no CLASS attribute 

is defined for el ementNode, then the SPAN tag surrounding el ementNode 
is removed. 

Returns 

Nothing. 

Enabler 

None. 

dreamweaver.stylePalette.attachExterna§StySesheet{) 

Availability 

Dreamweaver 4.0 

Description 

Displays a dialog box allowing users to attach an external style sheet. 

Arguments 

None. 

Returns 

Nothing. 
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dreamweaver.cssStylePalette.deleteSeiectedStyieC) 

Availability 

Dreamweaver 3.0 

Description 

Deletes from the document the style that is currently selected in the Style panel. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 



dreamweaver.cssStylePalette.dupSfcateSelectedStyleO 

Availability 

D ream weaver 3 . 0 

Description 

Duplicates the style that is currently selected in the Style panel and displays 
the Duplicate Style dialog box to let the user assign a name or selector to 
the new style. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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dreamweaver.cssStyIePaIette 0 ed§tSe!ectedStyle() 

Availability 

Dreamweaver 3.0 

Description 

Opens the Style Definition dialog box for the style that is currently selected in 
the Style panel. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

drearnweaver H cssStyIePaIefte,edatSty1eSheet(5 

Availability 

Dreamweaver 3.0 

Description 

Opens the Edit Style Sheet dialog box. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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dreamweaver.cssStylePalette.getSelectedStyleO 

Availability 

Dreamweaver 3.0 

Description 

Gets the name of the style that is currently selected in the Style panel. 

Arguments 

None. 

Returns 

A string representing the name of the style, or an empty string if no style 
is selected. 

Enabler 

None. 

Example 

If the style red is selected, as shown, a call to 

dw. cssStyl ePal ette . getSel ectedStyl e( ) returns "red". 
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dreamweaver.cssStylePalette.getSelectedlargetO 



Availability 

Dreamweaver 3.0 

Description 

Gets the selected element in the Apply To pop-up menu at the top of the 
Style panel. 

Arguments 

None. 

Returns 

The object to which the style should be applied, or NULL if the target is the 
current selection. 

Enabler 

None. 

Example 

Before applying a style, use dw.cssStyl ePal ette.getSel ectedTarget( ) in 
case the user has changed the target, as shown. 
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For example: 

var currDOM = dw . getDocumentDOM( ) ; 

currDOM . appl yCSSStyl e( dw . ess Sty 1 ePal ette . getSel ectedTargeK ) , -> 
"codeRed" ) ; 
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dreamweaver.cssStylePalette.getStylesO 

Availability 

Dreamweaver 3.0 

Description 

Gets a list of all the class styles in the active document. 

Arguments 

None. 

Returns 

An array of strings representing the names of all class styles in the document. 

Enabler 

None. 

Example 

Assuming the CSS Styles panel setup shown in this example, a call to 
dw. cssStyl ePal ete . getStyl es( ) would return an array containing the 
following strings: 

• "bigCode" 

• "red" 

• "secti onHead" 
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dreamweaver.cssStylePalettejiewStyieC) 

Availability 

Dreamweaver 3.0 

Description 

Opens the New Style dialog box. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

External application functions 

External application functions handle operations related to the browsers and 
external editors defined in the Preview in Browser and External Editors 
preferences. These functions let you get information about these external 
applications and open files with them. 

dreamweaver^browseDocumentO 

Availability 

Dreamweaver 2.0, enhanced in 3.0 and 4.0. 
Description 

Opens the specified URL in the specified browser. 

Arguments 

filename, {browser} 

• fi 1 eName is the name of the file to be opened, expressed as an absolute URL. 

• browser, added in Dreamweaver 3, specifies which browser to use. This 
argument can be the name of a browser as defined in the Preview in Browser 
preferences or either ' pri ma ry ' or ' second a ry '. If omitted, the URL is 
opened in the users primary browser. 

Returns 

Nothing. 

Enabler 

None. 
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Example 

The following function uses dreamweaver . browseDocument ( ) to open the 
Hotwired home page in a browser: 

function goToHotwi red ( ) { 

dreamweaver . browseDocument ( ' http : //www. hotwi red . com/ ' ) ; 

} 

In Dreamweaver 4, you can expand this operation to open the document in 
Internet Explorer using the following code: 

function goToHotwi red ( ) { 

var prevBrowsers = dw . getBrowserLi st ( ) ; 
var theBrowser = " " ; 

for (var i=l; i < prevBrowsers . 1 ength ; i+2){ 

if (prevBrowsers[i ] . i ndexOf ( ' Iexpl ore . exe ' ) != -1){ 
theBrowser = prevBrowsers[i ] ; 
break ; 

} 

} 

dw. brows e Document ( 'http: //www. hotwi red .com/ ' , theBrowser) ; 

} 

For more information on dw . getBrowserLi st( ), see 
"dream weaver.getBrowserListQ" on page 244. 

dreamweavef\getBrowserList() 

Availability 

Dreamweaver 3.0 

Description 

Gets a list of all the browsers in the Preview in Browser submenu. 

Arguments 

None. 

Returns 

An array containing a pair of strings for each browser in the list. The first string in 
each pair is the name of the browser, and the second string is its location on the 
users machine, expressed as a file:// URL. If no browsers appear in the submenu, 
the function returns nothing. 

Enabler 

None. 
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dreamweaver.gefExtensionEdstorL§si{) 

Availability 

Dreamweaver 3.0 

Description 

Gets a list of editors for the specified file from the External Editors preferences. 

Arguments 

fileURL 

fi 7 eURL can be a complete file:// URL, a file name, or a file extension (including 
the period) . 

Returns 

An array containing a pair of strings for each editor in the list. The first string in 
each pair is the name of the editor, and the second string is its location on the 
user's machine, expressed as a file:// URL. If no editors appear in the preferences, 
the function returns an array of one empty string. 

Enabler 

None. 

Example 

A call to dw. get Ex ten si onEdi tor Li st ( " . gi f " ) might return an array 
containing the following strings: 

• "Fireworks 3" 

• "fi 1 e: ///C | /Program Fi 1 es/Macromedi a/ Fi reworks 3/Fireworks 
3 . exe" 

dreamweaver«getExterna!TextEdator() 

Availability 

Dreamweaver 4.0 

Description 

Gets the name of the currently configured external text editor. 

Arguments 

None. 

Returns 

A string containing the name of the text editor suitable for presentation in the UI, 
not the full path. 

Enabler 

None. 
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dreamweaver.gefFrimaryBrowserQ 

Availability 

Dreamweaver 3.0 

Description 

Gets the path to the primary browser. 

Arguments 

None. 

Returns 

A string containing the path on the users hard drive to the primary browser, 
expressed as a file:// URL, or nothing if no primary browser is defined. 

Enabler 

None. 



drearnweaver H getPnrnaryExtensionEdBtor{) 

Availability 

Dreamweaver 3.0 

Description 

Gets the primary editor for the specified file. 

Arguments 

fileURL 

Returns 

An array containing a pair of strings. The first string in the pair is the name of 
the editor, and the second string is its location on the users machine, expressed 
as a file:// URL. If no primary editor is defined, the function returns an array of 
one empty string. 

Enabler 

None. 
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dreamweaver.getSeeondaryBrowserQ 

Availability 

Dreamweaver 3.0 

Description 

Gets the path to the secondary browser. 

Arguments 

None. 

Returns 

A string containing the path on the users hard disk to the secondary browser, 
expressed as a file:// URL, or nothing if no secondary browser is defined. 

Enabler 

None. 

dreamweaver H openWithApp(5 

Availability 

Dreamweaver 3.0 

Description 

Opens the specified file with the specified application. 

Arguments 

fileURL, appURL 

• fileURL is the path to the file to be opened, expressed as a file:// URL. 

• a ppURL is the path to the application that is to open the file, expressed as a 
file: // URL. 

Returns 

Nothing. 

Enabler 

None. 
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dreamweaver.openWithBrowseDialogO 

Availability 

Dreamweaver 3.0 

Description 

Opens the Select External Editor dialog box to let the user choose the application 
with which to open the specified file. 

Arguments 

fileURL 

Returns 

Nothing. 

Enabler 

None. 

drearnweaver H openWithExternalTextEditor{) 

Availability 

Dreamweaver 3.0 

Description 

Opens the current document in the external text editor specified in the External 
Editors preferences. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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dreamweaver.openWith!mageEd[tor() 

Availability 

Dreamweaver 3.0 

Description 

Opens the specified file with the specified image editor. 

Note: This function invokes a special Fireworks integration mechanism that returns 
information to the active document if Fireworks is specified as the image editor. To prevent 
errors if no document is active, this function should never be called from the Site window. 

Arguments 

fileURL, appURL 

• fileURL is the path to the file to be opened, expressed as a file:// URL. 

• appURL is the path to the application with which to open the file, expressed as a 
file:// URL. 

Returns 

Nothing. 

Enabler 

None. 
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File manipulation functions 

File manipulation functions deal with creating, opening, and saving documents, 
and with exporting cascading style sheets to external files. They accomplish such 
tasks as browsing for files or folders, creating files based on templates, closing 
documents, and getting information about recently opened files. 

dreamweaver.browseForFileURLO 

Availability 

Dreamweaver 1.0, enhanced in 2.0, 3.0 and 4.0 
Description 

Opens the specified type of dialog box with the specified label in the title bar. 
Arguments 

openSel ectOrSave, [ti tl eBarLabel }, {bShowPrevi ewPane}, 
(bSupressSi teRootttarni ngs }, {arrayOfExtensi ons } 

• openSel ectOrSave indicates the type of dialog box: open, sel ect, or save. 

• ti tl eBarLabel , added in Dreamweaver 2, is the label that should appear in 
the title bar of the dialog box. If this argument is omitted, Dreamweaver uses 
the default label supplied by the operating system. 

• bShowPrevi ewPane, added in Dreamweaver 2, is a Boolean value indicating 
whether to display the image preview pane in the dialog box. If this argument is 
true, the dialog box filters for image files; if omitted, it defaults to f a 1 se. 

• bSupressSi teRootblarni ngs, added in Dreamweaver 3, is a Boolean value 
indicating whether to suppress warnings about the selected file being outside 
the site root. If this argument is omitted, it defaults to f al se. 

• arrayO f Ex tens ions, added in Dreamweaver 4, is an array of strings for 
specifying the "Files of type" list menu default appearance at the bottom of the 
dialog box. The proper syntax is menuEntryText | .xxx[ ; .yyy ; .zzz] | CCCC | , 
where menuEntryText is the name of the file type to appear. The extensions 
can be specified as . xxxE ; . yyy; . zzz] or CCCC, where . xxx specifies the file 
extension for the file type (optionally, . yyy and . zzz specify multiple file 
extensions) and CCCC is the four-character file type constant for use on the 
Macintosh. 

Returns 

A string containing the name of the file, expressed as a file:// URL. 

Enabler 

None. 
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dreamweaver.browseForFolderURL{) 

Availability 

Dreamweaver 3.0 

Description 

Opens the Choose Folder dialog box with the specified label in the title bar. 
Arguments 

{ ti tl eBar Label }, (di recto ryToSt art In} 

• tl tl eBar Lab el is the label that should appear in the title bar of the dialog box. 
If omitted, ti tl eBa r Label defaults to "Choose Folder." 

• di recto ryToStar tin is the path to the directory to start in, expressed as a 
file:// URL. 

Returns 

A string containing the name of the folder, expressed as a file:// URL. 

Enabler 

None. 

Example 

The following code returns the URL of a folder: 

return dw.browseForFol derURK ' Sel ect a Folder', 
dw. getSi teRoot( ) ) ; 

dreamweaver n c!oseDocLimenf() 

Availability 

Dreamweaver 3.0 

Description 

Closes the specified document. 

Arguments 

documentObject 

documentObject is the object at the root of a documents DOM tree (the value 
returned by d reamwea ver . getDocumentDOM( )). If documentObject refers to the 
active document, the Document window might not close until the script that calls 
this function finishes executing. 

Returns 

Nothing. 

Enabler 

None. 
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dreamweaver.createDocumentO 

Availability 

Dreamweaver 2.0 

Description 

Opens a new document either in the same window or in a new window. The new 
document becomes the active document. 

Note: This function can be called only from menus.xml or a command or Property 
Inspector file. If a behavior action or object tries to call this function, Dreamweaver displays 
an error message. 

Arguments 

{ bOpenlnSameMi ndow) 

bOpenlnSameb/i ndow is a Boolean value indicating whether to open the new 
document in the current window. If bOpen I nSameb/i ndow is fal se or omitted, 
or the function is called on the Macintosh, the new document opens in a 
separate window. 

Returns 

The document object for the newly created document. This is the same value 
returned by dreamwea ver . getDocumentDOM( ). 

Enabler 

None. 



dreamweaver.exportCSSQ 

Availability 

D ream weaver 3 . 0 

Description 

Opens the Export Styles as CSS File dialog box. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamwea ver . ca n Export CSS ( ) 
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dreamweaver.exportEditabSeReggonsAsXMLO 

Availability 

Dreamweaver 3.0 

Description 

Opens the Export Editable Regions as XML dialog box. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

dreamweaver.getRecentFileListO 

Availability 

D ream weaver 3 . 0 

Description 

Gets a list of all the files in the recent files list at the bottom of the File menu. 

Arguments 

None. 

Returns 

An array of strings representing the paths of the most recently accessed files, 
expressed as file:// URLs. If there are no recent files, the function returns nothing. 

Enabler 

None. 

drearnweaverJmportXMLIntoTemplate{) 

Availability 

D ream weaver 3 . 0 

Description 

Opens the Import XML dialog box. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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dreamweaver.newFromTemplateQ 

Availability 

Dreamweaver 3.0 

Description 

Creates a new document from the specified template. If no argument is supplied, 
the Select Template dialog box appears. 

Arguments 

{ tempi ateURLj, bmaintain 

• temp 1 dteURL is the path to a template in the current site, expressed as a 
file: // URL. 

• bin a i nta i n is a Boolean, trueorfalse, indicating whether or not to maintain 
the link to the original template. 

Returns 

Nothing. 

Enabler 

None. 



dreamweaver.openDocumentQ 

Availability 

Dreamweaver 2.0 

Description 

Opens a document for editing in a new Dreamweaver window and gives it the 
focus. To the user, the effect is the same as choosing File > Open and selecting a 
file. If the specified file is already open, the window containing the document 
comes to the front. The window containing the specified file becomes the 
currently selected document. In Dreamweaver 2, if check in/check out is enabled, 
the file is checked out before it is opened. In Dreamweaver 4, you must use 
dreamweaver . openDocumentFromSi te( ) to get this behavior. 

Note: This function cannot be called from Behavior action or object files. An error 
will result. 

Arguments 

fi leName 

fi 1 eName is the name of the file to be opened, expressed as a URL. If the URL is 
relative, it is relative to the file containing the script that called this function. 

Returns 

The document object for the specified file. This is the same value that is returned 

by dreamweaver . ge t Document DOM ( ). 
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Enabler 

None. 

dreamweaver.openDocumentFromSiteO 

Availability 

D ream weaver 3 . 0 

Description 

Opens a document for editing in a new Dreamweaver window and gives it the 
focus. To the user, the effect is the same as double-clicking a file in the Site 
window. If the specified file is already open, the window containing the document 
comes to the front. The window containing the specified file becomes the 
currently selected document. 

Note: This function cannot be called from Behavior action or object files. An error 
will result. 

Arguments 

fi leName 

fi 1 eName is the name of the file to be opened, expressed as a URL. If the URL is 
relative, it is relative to the file containing the script that called this function. 

Returns 

The document object for the specified file. This is the same value that is returned 

by dreamweaver . ge t Document DOM ( ). 

Enabler 

None. 

dreamweaver.openSnFrameQ 

Availability 

Dreamweaver 3.0 

Description 

Opens the Open In Frame dialog box. When the user selects a document, it is 
opened into the active frame. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamweaver . canOpen In Frame ( ) 
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dreamweaver.reSeaseOocumentQ 

Availability 

Dreamweaver 2.0 

Description 

Explicitly releases a previously referenced document from memory. 

Documents referenced by dreamweaver . getObjectTags ( ), 
dreamweaver . getObjectRef s ( ), dreamweaver . ge t Document Pa t h ( ), or 
dreamweaver . getDocumentDOM( ) are automatically released when the script that 
contains the call finishes executing. If the script opens many documents, you must 
use this function to explicitly release documents before finishing the script to 
avoid running out of memory. 

Note: This function is relevant only for documents that were referenced by a URL, that 
are not currently open in a frame or Document window, and that are not extension files. 
(Extension files are loaded into memory at startup and are not released until you quit 
Dreamweaver.) 

Arguments 

documentObject 

documentObject is the object at the root of a documents DOM tree (the value 
returned by dreamweaver . getDocumentDOM( )). 

Returns 

Nothing. 

Enabler 

None. 



dreamweaver D revertDocument() 

Availability 

Dreamweaver 3.0 

Description 

Reverts the specified document to the previously saved version. 

Arguments 

documentObject 

documentObject is the object at the root of a documents DOM tree (the value 
returned by dreamweaver . getDocumentDOM( )). 

Returns 

Nothing. 

Enabler 

dreamweaver . canRevertDocument ( ) 
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d reamweaver.save AS \ {) 



Availability 

Dreamweaver 3.0 

Description 

Saves all open documents, opening the Save As dialog box for any documents that 
have not previously been saved. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamweaver . canSaveAl 1 ( ) 
dreamweaver.saveOocument() 

Availability 

Dreamweaver 2.0 

Description 

Saves the specified file on a local drive. 

Note: In Dreamweaver 2, if the file is read-only, Dreamweaver tries to check it out. If 
the document is still read-only after this attempt-or if it cannot be created-an error 
message appears. 

Arguments 

documentObject, {fileilRL} 

• documentObject is the object at the root of a documents DOM tree (the value 
returned by dreamweaver . ge t Document DOM ( )). 

• f 7 leURL is a URL representing a location on a local drive. If the URL is 
relative, it is relative to the extension file. In Dreamweaver 2, this argument 
is required. If fileURLis omitted in Dreamweaver 4, the file is saved to its 
current location if it has been previously saved; otherwise, a Save dialog 
box appears. 

Returns 

A Boolean value indicating success (true) or failure (fal se). 
Enabler 

dreamweaver . canSaveDocument ( ) 
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dreamweaver.saveDocumentAsQ 

Availability 

Dreamweaver 3.0 

Description 

Opens the Save As dialog box. 

Arguments 

documentObject 

documentObject is the object at the root of a documents DOM tree (the value 
returned by dreamwea ver . getDocumentDOM( )). 

Returns 

Nothing. 

Enabler 

None. 

dreamweaver D saveDocumentAsTemp]ate() 

Availability 

Dreamweaver 3.0 

Description 

Opens the Save As Template dialog box. 

Arguments 

documentObject 

documentObject is the object at the root of a documents DOM tree (the value 
returned by dreamwea ver . getDocumentDOM( )). 

Returns 

Nothing. 

Enabler 

dreamwea ver . canSaveDocumentAsTempl ate( ) 
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dreamweaver.saveFramesetQ 

Availability 

Dreamweaver 3.0 

Description 

Saves the specified frameset, or opens the Save As dialog box if the frameset has 
not previously been saved. 

Arguments 

documentObject 

documentObject is the object at the root of a documents DOM tree (the value 
returned by dreamwea ver . getDocumentDOM( )). 

Returns 

Nothing. 

Enabler 

dreamwea ver . ca n Save Frameset ( ) 
dreamweaver.saveFrarnesetAsQ 

Availability 

Dreamweaver 3.0 

Description 

Opens the Save As dialog box for the frameset file that includes the 
specified DOM. 

Arguments 

documentObject 

documentObject is the object at the root of a documents DOM tree (the value 
returned by dreamweaver . getDocumentDOM( )). 

Returns 

Nothing. 

Enabler 

dreamweaver . ca n Save Frameset As ( ) 
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Find/replace functions 



Find/ replace functions handle find and replace operations. They cover both basic 
functionality, such as finding the next instance of a search pattern, and complex 
replacement operations that require no user interaction. 

dreamweaveriindNextQ 

Availability 

Dreamweaver 3-0 

Description 

Finds the next instance of the search string that was specified previously by 
dreamweaver . setUpFind(),by dreamwea ver . setUpCompl exFi nd ( ), or by the 
user in the Find dialog box, and selects the instance in the document. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamweaver . canFi ndNext( ) 
d reamweaver,, replaceQ 

Availability 

D ream weaver 3 . 0 

Description 

Verifies that the current selection matches the search criteria that was 
specified previously by dreamweaver . setUpFi ndRepl ace( ), by 
dreamweaver . setUpCompl exFi ndRepl ace( ), or by the user in the Replace 
dialog box; then replaces it with the content specified in that query. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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dreamweaver.replaceAISQ 



Availability 

Dreamweaver 3.0 

Description 

Replaces each section of the current document that matches the search criteria 
that was specified previously by dreamweaver . setUpFi ndRepl ace( ), by 
dreamweaver . setUpCompl exFi ndRepl ace( ), or by the user in the Replace 
dialog box, with the content specified in that query. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

dreamweaver,setUpComplexFind() 

Availability 

Dreamweaver 3.0 

Description 

Prepares for an advanced text or tag search by loading the specified XML query. 

Arguments 

xml QueryStri ng 

xml QueryStri ng is a string of XML code beginning with <dwquery> and ending 
with </dwquery>. (To get a string of the proper format, set up the query in the 
Find dialog box, click the Save Query button, open the query file in a text editor, 
and copy everything from the beginning of the <dwquery> tag to the end of the 
</dwquery> tag.) 

Returns 

Nothing. 

Enabler 

None. 
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Example 

The first line of the following code sets up a tag search and specifies that the scope 
of the search should be the current document; the second line performs the 
search operation: 

dw. setUpCompl exFi nd( ' <dwquery>< query pa rams matchcase="fal se" -< 
i gnorewhi tespace="true" useregexp="fal seVXfi ndXqtag qname="a "X 
<qattri bute qname=" href " qcompa re=" = " qval ue="#"X/qattri buteX 
<qattn'bute qname="onMouseOut" qcompa re="=" qvalue="" qnegate="true"X 
</qattri buteX/qtagX/f i nd></dwquery> ' ) ; dw.fi ndNext( ) ; 

dreamweaver.setUpComplexFmdReplace() 

Availability 

Dreamweaver 3.0 

Description 

Prepares for an advanced text or tag search by loading the specified XML query. 

Arguments 

xml QueryStri ng 

xml QueryStri ng is a string of XML code beginning with <dwquery> and ending 
with </dwquery>. (To get a string of the proper format, set up the query in the 
Find dialog box, click the Save Query button, open the query file in a text editor, 
and copy everything from the beginning of the <dwquery> tag to the end of the 

</dwquery> tag.) 

Returns 

Nothing. 

Enabler 

None. 

Example 

The first statement in the following code sets up a tag search and specifies that the 
scope of the search should be four files; the second statement performs the search 
and replace operation: 

dw. setUpCompl exFi ndRepl ace( ' <dwqueryX query pa rams 
matchcase="fal se" -< 

i gnorewhi te spa ce=" true" useregexp=" fa 1 seVXfi ndXqtag qname="a "X 

<qattribute qname=" href " qcompa re=" = " qval ue="#"X/qattri buteX 

<qattribute qname="onMouseOut " qcompare="=" qvalue=" M -< 

qnegate="true"X/qattri buteX/qtagX/f i ndXrepl ace 

acti on="setAttri bute" paraml="onMouseOut" -> 

pa ram2=" this. style. col or=' #000000' ;-> 

thi s . styl e. ton tWei ght=' normal ' "/></dwquery> ' ) ; 

dw. repl aceAl 1 ( ) ; 
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dreamweaver.setUpFindO 



Availability 

Dreamweaver 3.0 

Description 

Prepares for a text or HTML source search by defining the search parameters for a 
subsequent dw.fi ndNextO operation. 

Arguments 

searchObject 

searchObject is an object for which the following properties can be defined: 

• s e a r ch S t r i n g is the text to search for. 

• searchSource is a Boolean value indicating whether to search the HTML 
source. 

• {matchCase} is a Boolean value indicating whether the search is case-sensitive. 
If this property is not explicitly set, it defaults to false. 

• { ignoreblh i tespace } is a Boolean value indicating whether white space 
differences should be ignored. 1 gnoretthi tespace defaults to fal se if 

useRegul arExpressi ons is true and true if useRegul arExpressi ons 
is fal se . 

• {useRegul arExpressi ons } is a Boolean value indicating whether the 
searchString uses regular expressions. If this property is not explicitly set, it 
defaults to fal se. 

Returns 

Nothing. 

Enabler 

None. 

Example 

The following code demonstrates three ways to create a searchObject object: 
var searchParams ; 

sea rchPa rams . searchStri ng = ' bgcol or="#FFCCFF" ' ; 
searchParams . searchSource = true; 
dw. setUp Find (search Pa rams) ; 

var searchParams = {searchString: ' bgcol or="#FFCCFF" ' , 

searchSource: true}; 

dw. setUp Find (search Pa rams) ; 

dw.setUpFind( {searchString: ' bgcol or="#FFCCFF" ' , searchSource: -< 
true} ) ; 
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dreamweaver.setUpFindReplaceQ 

Availability 

Dreamweaver 3.0 

Description 

Prepares for a text or HTML source search by defining the search parameters and 
the scope for a subsequent dw. rep 1 ace ( ) or dw . repl aceAl 1 ( ) operation. 

Arguments 

searchObject 

searchObject is an object for which the following properties can be defined: 

• s e a r ch S t r i n g is the text to search for. 

• repl aceStri ng is the text with which to replace the selection. 

• searchSource is a Boolean value indicating whether to search the 
HTML source. 

• (matchCase} is a Boolean value indicating whether the search is case-sensitive. 
If this property is not explicitly set, it defaults to f a 1 se. 

• { ignoreblh 1 tespace } is a Boolean value indicating whether white space 
differences should be ignored. ignoreWhi tespace defaults to fal se if 

useRegul arExpressi ons is true and true if useRegul a rExpressi ons 
is fal se . 

• {useRegul a rExpressi ons } is a Boolean value indicating whether the 
searchString uses regular expressions. If this property is not explicitly set, it 
defaults to fal se. 

Returns 

Nothing. 

Enabler 

None. 
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Example 

The following code demonstrates three ways to create a searchObject object: 

var searchParams ; 

sea rchPa rams . searchStri ng = ' bgcol or="#FFCCFF'" ; 
searchParams . repl aceStri ng = ' bgcol or="#CCFFCC" ' ; 
sea rchPa rams . sea rchSource = true; 
dw. setUp Fi nd Repl ace ( searchParams ) ; 

var searchParams = { sea rchStri ng : ' bgcol or="#FFCCFF" ' , 
repl aceStri ng : ' bgcol or="#CCFFCC" ' , sea rchSource : true}; 
dw. setUp Fi nd Repl ace ( searchParams ) ; 

dw. setUp Find Repl ace ( {search St ring : 'bgcol or="#FFCCFF" ' , 
repl aceStri ng : ' bgcol or="#CCFFCC" ' , sea rchSource : true}); 

dreamweaver.showFmdDialogO 

Availability 

Dreamweaver 3.0 

Description 

Opens the Find dialog box. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamweaver . can Show Fi nd Di al og( ) 

dreamweaver D showFindReplaceDialog() 

Availability 

D ream weaver 3 . 0 

Description 

Opens the Replace dialog box. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamweaver . can Show Fi ndDi al og( ) 
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Frame and frameset functions 



Frame and frameset functions cover only two tasks: getting the names of the 
frames in a frameset and splitting a frame in two. 

dofY^getFrameNamesQ 

Availability 

Dreamweaver 3.0 

Description 

Gets a list of all the named frames in the frameset. 

Arguments 

None. 

Returns 

An array of strings, each a name of a frame in the current frameset. Any unnamed 
frames are skipped. If none of the frames in the frameset is named, an empty array 
is returned. 

Enabler 

None. 

Example 

For a document containing four frames, two of which are named, a call to 

dw. getDocumentDOM( ) . getFrameNames ( ) might return an array containing the 

following strings: 

• "navframe" 

• "main_content" 

domJsDocumentlnFrameO 

Availability 

Dreamweaver 4.0 

Description 

Identifies whether or not the current document is being viewed inside a frameset. 

Arguments 

None. 

Returns 

Returns true if the document is in a frameset. Returns fal se otherwise. 

Enabler 

None. 
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dom.saveAHFrarrsesQ 

Availability 

Dreamweaver 4.0 

Description 

If the given document is a frameset or inside a frameset, saves all the frames and 
framesets from the same Document window. If the given document is not in a 
frameset, just saves the document. Opens the Save As dialog box for any 
documents that have not been previously saved. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

dom.splstFrameQ 

Availability 

Dreamweaver 3.0 

Description 

Splits the selected frame vertically or horizontally. 

Arguments 

spl i tDi recti on 

spl itDi recti on must be one of the following: "up", "down", "left", or 
"right". 

Returns 

Nothing. 

Enabler 

dom.canSpl i tFrame( ) 
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Genera! editing functions 

General editing functions handle common editing tasks that happen in the 
Document window. These functions insert text, HTML, and objects; apply, 
change, and remove font and character markup; modify tags and attributes; 
and more. 

dom.appSyCharacteryarkup() 

Availability 

D ream weaver 3 . 0 

Description 

Applies the specified type of character markup to the selection. If the selection is 
an insertion point, applies the specified character markup to any subsequently 
typed text. 

Arguments 

tagName 

tagName is the tag name associated with the character markup. It must be one of 
the following strings: "b", "cite", "code", "dfn", "em", "i", "kbd", "samp", 
"s", "strong", "tt", "u", or "var". 

Returns 

Nothing. 

Enabler 

None. 

dom.appSyFontMarkupQ 

Availability 

Dreamweaver 3.0 

Description 

Applies the FONT tag and the specified attribute and value to the current selection. 

Arguments 

attribute, val ue 

• attribute must be "face", "si ze", or "col or". 

• val ue is the value that should be assigned to the attribute; for example, 

"Arial, Helvetica, sans-seri f ", "5", or "#FF0000". 

Returns 

Nothing. 

Enabler 

None. 
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dom,deleteSelectk>n() 

Availability 

Dreamweaver 3.0 

Description 

Deletes the selection in the document. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

dom.editAttributeQ 

Availability 

D ream weaver 3 . 0 

Description 

Displays the appropriate interface for editing the specified attribute. In most cases, 
this is a dialog box. This function is valid only for the active document. 

Arguments 

attribute 

Returns 

Nothing. 

Enabler 

None. 
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dom.exatBbckO 

Availability 

Dreamweaver 3.0 

Description 

Exits the current paragraph or heading block, leaving the cursor outside of all 
block elements. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

dom,getCharSet(} 

Availability 

Dreamweaver 4.0 

Description 

Returns the charset attribute in the meta tag of the document. 

Arguments 

None. 

Returns 

The encoding identity of the document. So, for example, in Larinl document, the 
function will return i s o - 8859 - 1 . 

dom.getFontMarkupQ 

Availability 

D ream weaver 3 . 0 

Description 

Gets the value of the specified attribute of the FONT tag for the current selection. 

Arguments 

attribute 

attribute must be "face", "si ze", or "col or". 
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Returns 

A string containing the value of the specified attribute, or an empty string if the 
attribute is not set. 

Enabler 

None. 

dom,getUnkHref{) 

Availability 

Dreamweaver 3.0 

Description 

Gets the link that surrounds the current selection. This function is equivalent to 
looping through the parents and grandparents of the current node until a link is 
found, and then calling get Attn' bute( 'HREF' ) on the link. 

Arguments 

None. 

Returns 

A string containing the name of the linked file, expressed as a file:// URL. 

Enabler 

None. 

dom.getUnkTargetQ 

Availability 

D ream weaver 3 . 0 

Description 

Gets the target of the link that surrounds the current selection. This function is 
equivalent to looping through the parents and grandparents of the current node 
until a link is found, and then calling getAttri bute( ' TARGET' ) on the link. 

Arguments 

None. 

Returns 

A string containing the value of the TARGET attribute for the link, or an empty 
string if no target is specified. 

Enabler 

None. 
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dom.getUstTag{) 

Availability 

Dreamweaver 3.0 

Description 

Gets the style of the selected list. 

Arguments 

None. 

Returns 

A string containing the tag associated with the list ( " u 1 " , " o 1 " , or " d 1 " ), or an 
empty string if no tag is associated with the list. This value is always returned in 
lowercase letters. 



Enabler 

None. 



dom.getTextAHgnmentQ 

Availability 

Dreamweaver 3.0 

Description 

Gets the alignment of the block that contains the selection. 

Arguments 

None. 



Returns 

A string containing the value of the ALIGN attribute for the tag associated with the 
block, or an empty string if the AL I GN attribute is not set for the tag. This value is 
always returned in lowercase letters. 



Enabler 

None. 
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dom.getTextFormat{) 

Availability 

Dreamweaver 3.0 

Description 

Gets the block format of the selected text. 

Arguments 

None. 

Returns 

A string containing the block tag associated with the text (for example, " p " , "hi", 
"pre", and so on, or an empty string if no block tag is associated with the 
selection). This value is always returned in lowercase letters. 

Enabler 

None. 

dom,hasCharacterfV1arkup(5 

Availability 

Dreamweaver 3.0 

Description 

Checks whether the selection already has the specified character markup. 

Arguments 

markupTagName 

markupTagName is the name of the tag you're checking for. It must be one of 
the following strings: "b", "cite", "code", "dfn", "em", "i", "kbd", "samp", 
"s", "strong", "tt", "u", or "var". 

Returns 

A Boolean value indicating whether the entire selection has the specified 
character markup. The function returns f a 1 se if only part of the selection has 
the specified markup. 

Enabler 

None. 
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domJndentQ 

Availability 

Dreamweaver 3.0 

Description 

Indents the selection using BLOCKQUOTE tags. If the selection is inside a list, 
indents the selection by nesting another list of the same type inside the 
current list. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 



domJnsertHTlVlL() 

Availability 

Dreamweaver 3.0 

Description 

Inserts HTML content into the document at the current insertion point. 
Arguments 

contentToInsert, (bReplaceCurrentSelection} 

• contentToInsert is the content you want to insert. 

• bRepl aceCurrentSel ecti on is a Boolean value indicating whether the 
content should replace the current selection. If bRepl aceCurrentSel ecti on is 
f a 1 se, the content is inserted after the current selection. 

Returns 

Nothing. 

Enabler 

None. 
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Example 

The following code inserts <b> 1 30< / b> into the current document: 

var theDOM = dw . getDocumentDOM( ) ; 
theDOM.insertHTMK '<b>130</b>' ) ; 

This appears in the Document window as: 



i^ -dom.inserlHTML [[ 



domJnsertObject(} 

Availability 

Dreamweaver 3.0 

Description 

Inserts the specified object, prompting the user for parameters if necessary. 

Arguments 

objectName 

objectName is the name of an object in the Configuration/Objects folder. 

Returns 

Nothing. 

Enabler 

None. 

Example 

A call to dreamweaver . ge t Document DOM ( ) . i nsertObject ( ' Button ' ) ; inserts 
a form button into the current document at the current insertion point or after 
the current selection. 

Note", Although object files can be stored in separate folders, it's important that their file 
names be unique. If a file called Button.htm exists in the Forms folder and also in the 
MyObjects folder, Dreamweaver cannot distinguish between them. 
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domJnsertIext{) 

Availability 

Dreamweaver 3.0 

Description 

Inserts text content into the document at the current insertion point. 
Arguments 

contentToInsert, (bRepl aceCurrentSel ecti on} 

• contentToInsert is the content you want to insert. 

• bRepl aceCurrentSel ecti on is a Boolean value indicating whether the 
content should replace the current selection. If bRepl aceCurrentSel ecti on 
is fal se, the content is inserted after the current selection. 

Returns 

Nothing. 

Enabler 

None. 

Example 

The following code inserts &1 1 ; b&gt ; 130&1 1 ; /b&gt ; into the 
current document: 

var theDOM = dw . getDocumentDOM( ) ; 
theDOM.insertTexK ' <b>130</b> ' ) ; 

This appears in the Document window as: 



j^!dominsertHTML(l 



fa si !§• §|? 
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dom.newBlockQ 



Availability 

Dreamweaver 3.0 

Description 

Creates a new block with the same tag and attributes as the block that contains the 
current selection, or creates a new paragraph if the cursor is outside of all blocks. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

Example 

If the current selection is inside a center- aligned paragraph, a call to 

dreamweaver . ge t Document DOM ( ) . newBl ock( ) inserts <p al i gn=" center") 
after the current paragraph. 

dom.notsfynashOb|ectChanged{) 

Availability 

Dreamweaver 4.0 

Description 

Informs Dreamweaver that the current Flash object file has changed. 
Dreamweaver updates the Preview display, resizing it as necessary and preserving 
the width and height ratio from the natural size. For example, Flash Text uses this 
to update the text in the Layout view as the user changes its properties in the 
Command dialog box. 

Arguments 

None. 

Returns 

Nothing. 
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dom.oistdentQ 

Availability 

Dreamweaver 3.0 

Description 

Outdents the selection. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

dom.removeCharacterMarkup() 

Availability 

D ream weaver 3 . 0 

Description 

Removes the specified type of character markup from the selection. 

Arguments 

tagName 

tagName is the tag name associated with the character markup. It must be one of 
the following strings: "b", "cite", "code", "dfn", "em", "i", "kbd", "samp", 
"s", "strong", "tt", "u", or "var". 

Returns 

Nothing. 

Enabler 

None. 



278 Chapter 20 



dom.removeFontMarkiipQ 

Availability 

Dreamweaver 3.0 

Description 

Removes the specified attribute and its value from a FONT tag. If removing the 
attribute would leave only <F0NT>, then the FONT tag is also removed. 

Arguments 

attribute 

attribute must be "face", "si ze", or "col or". 

Returns 

Nothing. 

Enabler 

None. 

dom,removeUnk() 

Availability 

Dreamweaver 3.0 

Description 

Removes the hyperlink from the selection. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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dom.resszeSeSectionQ 

Availability 

Dreamweaver 3.0 

Description 

Resizes the selected object to the specified dimensions. To resi2e a layer or hotspot, 

use dom. resi zeSel ecti on By ( ). 

Arguments 

newk/idth, newHeight 

Returns 

Nothing. 

Enabler 

None. 



dom,setAttributeWithErrorChecking{) 

Availability 

Dreamweaver 3.0 

Description 

Sets the specified attribute to the specified value for the current selection, 
prompting the user if the value is of the wrong type or if it is out of range. 
This function is valid only for the active document. 

Arguments 

attribute, value 

Returns 

Nothing. 

Enabler 

None. 
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dom.setLinkHref() 



Availability 

Dreamweaver 3.0 

Description 

Makes the selection a hyperlink or changes the value of the link that surrounds the 
current selection. 

Arguments 

linkHREF 

1 ink HREF is the URL (document-relative path, root- relative path, or 
absolute URL) to link to. If the argument is omitted, the Select HTML File 
dialog box appears. 

Returns 

Nothing. 

Enabler 

dom. canSetLi nkHref ( ) 



dom.setUnkTargetQ 

Availability 

Dreamweaver 3.0 

Description 

Sets the target of the link that surrounds the current selection. This function is 
equivalent to looping through the parents and grandparents of the current node 
until a link is found, and then calling setAttri bute( ' TARGET' ) on the link. 

Arguments 

{1 inkTarget} 

7 inkTarget is a string representing a frame or window name, or one of the 
reserved targets ("_self", "_parent", "_top", or "_blank"). If the argument is 
omitted, the Set Target dialog box appears. 

Returns 

Nothing. 

Enabler 

None. 
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dom.setUstBoxKand() 

Availability 

Dreamweaver 3.0 

Description 

Changes the kind of the selected SELECT menu. 

Arguments 

kind 

k 7 nd must be either "menu" or "list box". 

Returns 

Nothing. 

Enabler 

None. 

dom,showLiStPropertiesDiaIog() 

Availability 

Dreamweaver 3.0 

Description 

Opens the List Properties dialog box. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dom. canShowLi st Proper ti esDi al og( ) 

dom.setUstTagC) 

Availability 

Dreamweaver 3-0 

Description 

Sets the style of the selected list. 

Arguments 

7 istTag 

1 istTag is the tag associated with the list. It must be " o 1 " , " u 1 " , " d 1 " , or an 
empty string. 
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Returns 

Nothing. 

Enabler 

None. 

dom,setTextAlignment() 

Availability 

Dreamweaver 3.0 

Description 

Sets the ALIGN attribute of the block that contains the selection to the 
specified value. 

Arguments 

a 1 ignVal ue 

a 1 ignVal ue must be " 1 eft", "center", or "right". 

Returns 

Nothing. 

Enabler 

None. 

dom.setTextFjeyKmdC) 

Availability 

Dreamweaver 3-0 

Description 

Sets the format of the selected text field. 

Arguments 

fieldType 

fieldType must be "input", "textarea", or "password". 

Returns 

Nothing. 

Enabler 

None. 
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dom.showFontCoSorDiaSogQ 



Availability 

Dreamweaver 3.0 

Description 

Opens the Color Picker dialog box. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

dreamweaver.deleteSelectsonQ 

Availability 

Dreamweaver 3.0 

Description 

Deletes the selection in the active document or the Site window; or, on the 
Macintosh, the edit field that has focus in a dialog box or floating panel. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamweaver . can Del eteSel ecti on( ) 
dreamweaver,ed3tFontUst() 

Availability 

Dreamweaver 3.0 

Description 

Opens the Edit Font List dialog box. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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dreamweaver.getFontUst() 

Availability 

Dreamweaver 3.0 

Description 

Gets a list of all the font groups that appear in the text Property inspector and in 
the Style Definition dialog box. 

Arguments 

None. 

Returns 

An array of strings representing each item in the font list. 

Enabler 

None. 

Example 

For the default installation of Dreamweaver, a call to dw . getFont Li st ( ) would 
return an array containing the following items: 

• "Arial, Helvetica, sans-serif" 

• "Times New Roman, Times, serif" 

• "Courier New, Courier, mono" 

• "Georgia, Times New Roman, Times, serif" 

• "Verdana, Arial, Helvetica, sans-serif" 

dreamweaver D getFontStyIes{) 

Availability 

D ream weaver 4 . 0 

Description 

Returns the styles that a specified TrueType font supports. 

Arguments 

fontName 

ton tNdme is a string containing the name of the font. 
Returns 

An array of three Boolean values indicating what the font supports. The first 
indicates whether or not the font supports Bold, the second Italic, and the third 
whether or not the font supports both Bold and Italic together. 
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dreamweaver.getKeyStateQ 

Availability 

Dreamweaver 3.0 

Description 

Determines whether the specified modifier key is down. 

Arguments 

key 

key must be one of the following: "Cmd", "Ctrl "Al t", or "Shi ft". In 
Windows, "Cmd" and "Ctrl " both refer to the Control key; on the Macintosh, 
"Al t" refers to the Option key. 

Returns 

A Boolean value indicating whether the key is down. 

Enabler 

None. 

Example 

The following code checks that both the Shift and Control keys (Windows) or 
Shift and Command keys (Macintosh) are down before performing an operation: 

if (dw.getKeyStateCShiff) && dw.getKeyState( "Cmd" ) ) { 
// execute code 

} 

dreamweaver.getSysteniFontLast() 

Availability 

Dreamweaver 4.0 

Description 

Returns a list of fonts for the system. This function can get either all fonts or 
TrueType only. These fonts are needed for the Flash Text object. 

Arguments 

fontTypes 

fontTypes is a string containing either "al 1 " or "TrueType". 
Returns 

An array of strings containing all the font names; returns null if no fonts 
were found. 
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Global application functions 

Global application functions act on the entire application. They provide such 
functionality as quitting and accessing preferences. 

drearnweaver H getShowD8alogsOnfnsert{) 

Availability 

Dreamweaver 3.0 

Description 

Checks whether the Show Dialog When Inserting Objects option is turned on in 
the General preferences. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the option is on. 

Enabler 

None. 

dreamweaver.quitApplscatlonQ 

Availability 

Dreamweaver 3-0 

Description 

Quits Dreamweaver after the script that calls this function finishes executing. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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dreamweaver.showAboutBox{) 

Availability 

Dreamweaver 3.0 

Description 

Opens the About box. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 



dreamweaver.showPreferencesDialogO 

Availability 

D ream weaver 3 . 0 

Description 

Opens the Preferences dialog box. 

Arguments 

{whichTab} 

The agument must be one of the following strings: "general "external 
editors", "floaters", "fonts", "highlighting", "html colors", "html 
format", "html rewri ti ng", "i nvi si bl e el ements ", " 1 ayers ", 
"browsers", "qui ck tag edi tor ", " si te ftp", "status bar", "ess 
styles", and "translation". If Dreamweaver does not recognize the argument 
as a valid pane name, or if the argument is omitted, the dialog box opens to the 
last active pane. 

Returns 

Nothing. 

Enabler 

None. 
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Global document functions 



Global document functions act on the entire document. They check spelling, 
check target browsers, set page properties, and determine correct object references 
for elements in the document. 

domxheckSpellsngQ 

Availability 

Dreamweaver 3-0 

Description 

Checks the spelling in the document, opening the Check Spelling dialog box if 
necessary, and notifies the user when the check is complete. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

domxheckTargetBrowsersQ 

Availability 

Dreamweaver 3.0 

Description 

Runs a target browser check on the document. To run a target browser check on a 
folder or group of files, use si te . checkTa rgetBrowsers ( ). 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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dom.showPagePropertiesDiaSogO 

Availability 

Dreamweaver 3.0 

Description 

Opens the Page Properties dialog box. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

dreamweaver.geiESementRefQ 

Availability 

Dreamweaver 2.0 

Description 

Gets the Netscape or IE object reference for a specific tag object in the DOM tree. 

Arguments 

NSorlE, tagObject 

• NSorlE must be either "NS 4.0"or"IE 4 . 0". The DOM and rules for nested 
references differ in Navigator 4.0 and Internet Explorer 4.0. This argument 
specifies for which browser to return a valid reference. 

• tagObject is a tag object in the DOM tree. 
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Returns 

A string representing a valid JavaScript reference to the object, such as 

document . 1 ayers[ ' my Layer ' ]. 

• Dreamweaver returns correct references for Internet Explorer for A, AREA, 
APPLET, EMBED, D IV, SPAN, INPUT, SELECT, OPTION, TEXTAREA, OBJECT, and IMG 
tags. 

• Dreamweaver returns correct references for Navigator for A, AREA, APPLET, 
EMBED, LAYER, I LAYER, SELECT, OPTION, TEXTAREA, OBJECT, and IMG tags, and 
for absolutely positioned D I V and SPAN tags. For D I V and SPAN tags that are not 
absolutely positioned, Dreamweaver returns "cannot reference <tag>" . 

• Dreamweaver does not return references for unnamed objects. If an object does 
not contain either a NAME or an I D attribute, then Dreamweaver returns 
"unnamed < tag> " . If the browser does not support a reference by name, 
Dreamweaver references the object by index (for example, 

document .my form. a ppl ets[3]). 

• Dreamweaver returns references for named objects contained in unnamed 
forms and layers (for example, document . forms [2] . myCheckbox). 

Enabler 

None. 

History functions 

History functions deal with undoing, redoing, recording, and playing steps that 
appear in the History panel (programmed into the API as "palette"). A step is any 
repeatable change to the document or to a selection in the document. Methods of 
the dreamweaver . historyPalette object either control or act on the selection 
in the History panel, not in the current document. 

dornsedoQ 

Availability 

Dreamweaver 3.0 

Description 

Redoes the step that was just undone in the document. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dom . canRedo( ) 
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dom.undoQ 

Availability 

Dreamweaver 3.0 

Description 

Undoes the previous step in the document. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dom . canUndo( ) 

dreamweaver.getRedoTextQ 

Availability 

Dreamweaver 3.0 

Description 

Gets the text associated with the editing operation that will be redone if the user 
chooses Edit > Redo or presses Ctrl+Y (Windows) or Command+Y (Macintosh). 

Arguments 

None. 

Returns 

A string containing the text associated with the editing operation that will 
be redone. 

Enabler 

None. 

Example 

If the users last action was to make the selection bold, a call to 

dw. getRedoTexK ) would return " Repeat Apply Bold". 

dreamweaver.getUndoTextQ 

Availability 

Dreamweaver 3.0 

Description 

Gets the text associated with the editing operation that will be undone if the user 
chooses Edit > Undo or presses Ctrl+Z (Windows) or Command+Z (Macintosh). 
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Arguments 

None. 

Returns 

A string containing the text associated with the editing operation that will 
be undone. 

Enabler 

None. 

Example 

If the users last action was to apply a CSS style to a selected range of text, a call to 
dw. getUndoTexK ) would return "Undo Apply <span>". 

dreamweaver.playRecordedCommand{) 

Availability 

D ream weaver 3 . 0 

Description 

Plays the recorded command in the active document. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamweaver . can PI ay RecordedCommand ( ) 

d reamweaver. redo() 

Availability 

Dreamweaver 3.0 

Description 

Redoes the step that was just undone in the Document window, dialog box, 
floating panel, or Site window pane that has focus. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamweaver . canRedo( ) 
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dreamweaver.start Record ingQ 

Availability 

Dreamweaver 3.0 

Description 

Starts recording steps in the active document. The previously recorded command 
is immediately discarded. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamweaver . i sRecordi ng( ) (must return fal se) 

dreamweaver.stopRecordlngO 

Availability 

Dreamweaver 3.0 

Description 

Stops recording without prompting the user. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamweaver . i sRecordi ng( ) (must return true) 

d rearnweaver. u ndo{) 

Availability 

D ream weaver 3 . 0 

Description 

Undoes the previous step in the Document window, dialog box, floating panel, or 
Site window pane that has focus. 

Arguments 

None. 
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Returns 

Nothing. 

Enabler 

dreamweaver . canUndo( ) 

dreamweaverJisstoryPalette„cIearSteps(} 

Availability 

Dreamweaver 3.0 

Description 

Clears all steps from the History panel, and disables the Undo and Redo 
menu items. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

dreamweaver.historyPalettexopyStepsO 

Availability 

D ream weaver 3 . 0 

Description 

Copies the specified history steps to the clipboard. Dreamweaver warns the 
user of possible unintended consequences if the specified steps include an 
unrepeatable action. 

Arguments 

arrayOf Indices 

array Of Indices is an array of position indices in the History panel. 
Returns 

A string containing the JavaScript that corresponds to the specified history steps. 

Enabler 

None. 

Example 

The following code copies the first four steps in the History panel: 

dw. hi story Pal ette . copySteps( [0,1,2,3]); 
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dreamweaver.historyPalette,getSelectedSteps() 

Availability 

Dreamweaver 3.0 

Description 

Determines which portion of the History panel is selected. 

Arguments 

None. 

Returns 

An array containing the position indices of all the selected steps. 

Enabler 

None. 

Example 

If the second, third, and fourth steps are selected in the History panel, as shown, 
call to dw. hi story Pal ette . getSel ected Steps ( ) would return [1,2,3]. 
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dreamweaver.historyPaSette,getStepCount() 

Availability 

Dreamweaver 3.0 

Description 

Gets the number of steps in the History panel. 

Arguments 

None. 

Returns 

An integer representing the number of steps that are currently listed in the 
History panel. 

Enabler 

None. 



dreamweaver.hsstoryPaSette,gefStepsAsJavaScrBpt{) 

Availability 

Dreamweaver 3.0 

Description 

Gets the JavaScript equivalent of the specified history steps. 

Arguments 

arrayOflndi ces 

array Of Indices is an array of position indices in the History panel. 
Returns 

A string containing the JavaScript that corresponds to the specified history steps. 

Enabler 

None. 

Example 

If the three steps shown in this example are selected in the History panel, a call to 

dw. hi story Pal ette . get Steps As Java Scri pt( dw . hi story Pal ette . get Sel ec 
tedSteps( ) ) returns "dw . get Document DOM ( ) . i nsertText( 'Hey diddle 
diddle, a cat and a fiddle, the cow jumped over the 
moon . ' ) ; \ndw. get Document DOM ( ) . newBl ock( ) ; \n 

dw. get Document DOM ( ) . i nsertHTMK ' <img src=\ " . . /wdw99/50browsers/ 
images/ sun . gi f \ "> ' , true) ; \n": 
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dreamweaver.historyPalette,gefUndoState() 

Availability 

Dreamweaver 3.0 

Description 

Gets the current undo state. 

Arguments 

None. 

Returns 

The position of the Undo marker in the History panel. 

Enabler 

None. 

dreamweaver.hsstoryPalette,replaySteps() 

Availability 

D ream weaver 3 . 0 

Description 

Replays the specified history steps in the active document. Dreamweaver warns 
the user of possible unintended consequences if the specified steps include an 
unrepeatable action. 

Arguments 

arrayOflndi ces 

arrayOflndi ces is an array of position indices in the History panel. 
Returns 

A string containing the JavaScript that corresponds to the specified history steps. 

Enabler 

None. 

Example 

A call to dw. hi story Pal ette . repl aySteps( [0,2,3]) plays the first, third, and 
fourth steps in the History panel. 
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dreamweaver.historyPalette,saveAsConiniand(5 

Availability 

Dreamweaver 3.0 

Description 

Opens the Save As Command dialog box, which lets the user save the specified 
steps as a command. Dreamweaver warns the user of possible unintended 
consequences if the steps include an unrepeatable action. 

Arguments 

arrayOf Indices 

arrayOflndi ces is an array of position indexes in the History panel. 
Returns 

A string containing the JavaScript that corresponds to the specified history steps. 

Enabler 

None. 

Example 

The following code saves the fourth, sixth, and eighth steps in the History panel as 
a command: 

dw. hi story Pal ette . saveAsCommand ( [3,5,7]); 

drearnweaver u hfetoryPalette.setSelectedSteps{) 

Availability 

Dreamweaver 3.0 

Description 

Selects the specified steps in the History panel. 

Arguments 

arrayOflndi ces 

array Of Indices is an array of position indices in the History panel. If no 
argument is supplied, all steps are deselected. 

Returns 

None. 

Enabler 

None. 

Example 

The following code selects the first, second, and third steps in the History panel: 

dw. hi story Pal ette . setSel ectedSteps( [0 , 1 ,2] ) ; 
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dreamweaver.historyPalette,setUndoState() 

Availability 

Dreamweaver 3.0 

Description 

Performs the correct number of undo or redo operations to arrive at the specified 
undo state. 

Arguments 

undoState 

undoState is the object returned by dw. hi storyPal ette . getUndoState( ). 

Returns 

Nothing. 

Enabler 

None. 

HTM L style functions 

HTML style functions handle applying, creating, and deleting HTML styles. 
Methods of the dreamweaver . html Styl ePal ette object either control or act on 
the selection in the HTML Styles panel (programmed into the API as "palette"), 
not in the current document. 

dom.appSyHTMLStyleO 

Availability 

Dreamweaver 3.0 

Description 

Applies the specified HTML style to the current selection. This function is valid 
only for the active document. 

Arguments 

html Styl eName 

Returns 

Nothing. 

Enabler 

None. 
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dreamweaver.htrnSStylePalette.deleteSeIectedStySe{) 

Availability 

Dreamweaver 3.0 

Description 

Removes the selected style from the HTML Styles panel. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamweaver . html Styl ePal ette . canEdi tSel ecti on( ) 

dreamweaverJitmlStySePaSette,duph*cateSelectedSty!e() 

Availability 

Dreamweaver 3.0 

Description 

Duplicates the selected style and opens the Define HTML Style dialog box. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamweaver . html Styl e Pal ette . canEdi tSel ecti on ( ) 

dreamweaver.htrnlStylePaSette,edstSelectedStySe() 

Availability 

D ream weaver 3 . 0 

Description 

Opens the Define HTML Style dialog box for the selected style. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamweaver . html Styl e Pal ette . canEdi tSel ecti on ( ) 
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dreamweaver.htrnSStylePalette.getSelectedStyleC) 

Availability 

Dreamweaver 3.0 

Description 

Gets the name of the selected style in the HTML Style panel. 

Arguments 

None. 

Returns 

A string containing the name of the selected style. 

Enabler 

None. 

dreamweaver.htmSStylePalette.getStylesO 

Availability 

D ream weaver 3 . 0 

Description 

Gets a list of all of the names of the defined HTML styles. 

Arguments 

None. 

Returns 

An array of strings, each representing the name of an HTML style. If no HTML 
styles are defined, an empty array is returned. 

Enabler 

None. 
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dreamweaver.htrnSStylePalette.newStySe{) 

Availability 

Dreamweaver 3.0 

Description 

Opens the Define HTML Style dialog box for a new, untitled style. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

dreamweaver.htmSStylePalette.setSelectedStyleC) 

Availability 

D ream weaver 3 . 0 

Description 

Selects the specified style in the HTML Style panel. 

Arguments 

html Styl eName 

Returns 

Nothing. 

Enabler 

None. 



The Dreamweaver JavaScript API 303 



JavaScript Debugger functions 



These commands customize the Dreamweaver JavaScript Debugger behavior. For 
more information about the Dreamweaver JavaScript Debugger, see "JavaScript 
Debugger Modules" on page 61. 

domJnstrumentDocument () 

Availability 

Dreamweaver 4.0 

Description 

Creates the debug version of the document and any external .js files it 
references. This function parses the JavaScript in the document and calls the 
debuggerModul e for code snippets to insert at various points in the JavaScript 
file. The debuggerModu 1 e is also notified of syntax errors and warnings. This 
function fails under any of the following conditions: syntax errors, a file error, or 
the document cannot be debugged for some reason. Temporary files are never 
deleted immediately, even if the function fails. 

Arguments 

debuggerModul e, outputFi 1 eName 

• debuggerModul e is the name of a special Dreamweaver module file that 
implements the instrumentation API. The module is located in the 
Configuration/Debugger folder of the Dreamweaver Program Files directory. 

• outputFi 1 eName is optional; it is the name to use for the debug version of the 
.htm file. If omitted, a temporary file is created. The temporary file is deleted 
when Dreamweaver exits. If the specified outputFi 1 eName exists, the existing 
file is replaced. The file is always written in the same directory as the source 
document, so it cannot have the same name as the source document. If a path 
is specified, it is ignored. The debug version of externally referenced .js files is 
named by adding outputFi 1 eName to the beginning of the original file name 
of the .js file. 

Returns 

An array of pairs of file URLs. Each pair consists of the URL of the original 

source file followed by the URL of the debug version that was created. The 

first pair is always the .htm files and any subsequent entries are .js files referenced 

by the .htm file. If the function fails, then null is returned. Note that a 

pair of URLs is actually two entries in the array. So, ifreturnValue = 

dom. instrumentDocument(test . htm), then returnVal ue[0] is the URL of 

test.htm and returnValue[l] is the URL of the debug version of test.htm. 
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dreamweaver.debugDociimentQ 



Availability 

Dreamweaver 4.0 

Description 

Creates the debug version of the current document and starts the debugger. This 
function can be used only with one of the browsers for which Dreamweaver 
supports JavaScript debugging (see "dreamweaver.getDebugBrowserList()" on 
page 305). This function does not prompt the user if it cannot determine the 
browser type. If syntax errors or warnings occur, a Results window is opened to 
display the messages. If no errors occur, the debug version of the HTML 
document appears in the specified browser. If warnings occur, but no errors, the 
Results window appears and debugging begins. 

The creation of the debug version is implemented with a call to 
dom.instrumentDocumentO using the one of the default instrumentation 
modules. The debug version of the document is temporary and is deleted the next 
time the debugger starts or when Dreamweaver exits. 

Arguments 

fileName, {browserName} 

• fi 1 eName is the name of the file to be opened, expressed as an absolute URL. 

• browserName is optional; it specifies the name of the target browser as defined 
in the Preview settings in Browser Preferences. It can also be 'primary' or 
'secondary'. If omitted, the primary browser is used by default. 

Returns 

Nothing. 

dreamweavengetDebugBrowserListO 

Availability 

Dreamweaver 4.0 

Description 

Returns the defined browsers for which Dreamweaver supports JavaScript 
debugging. For Windows, Dreamweaver supports debugging only in Internet 
Explorer 5-0 and later and Netscape 4.5 and later. For Macintosh, Dreamweaver 
supports debugging only in Netscape 4.5 and later. 

Arguments 

None. 

Returns 

An array of browser names in the same format as that returned by 

getBrowserLi st( ). 
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dreamweaver.getSsAnyBreakpointsQ 

Availability 

Dreamweaver 4.0 

Description 

Finds if any breakpoints are set in any files. 

Arguments 

None. 

Returns 

bBreakpointsSet 

Boolean true if any breakpoints are set in any files. 

dreamweaver.removeAHBreakpo§nts() 

Availability 

Dreamweaver 4.0 

Description 

Removes all breakpoints in all files. 

Arguments 

None. 

Returns 

Nothing. 
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dreamweaver.startDebuggerQ 



Availability 

Dreamweaver 4.0 

Description 

Opens the Debugger window with original source .htm file and .js files listed in 
sourceFileListO, then launches the browser with the debug version file 
specified by debugFi 1 eName ( ) . This function does not prompt the user if it 
cannot determine the browser type. 

The creation of the debug version is accomplished with a call to 

dotn. i instrument Document ( ). 

Arguments 

debugFi 1 eName, sourceFi leList, is Temp Fi les, {browserName} 

• debugFi 7 eName is the name of a debug version file to launch in the browser. 

• sourceFi 1 eL i s t is an array of URL pairs comprising the source file and the 
instrumented file; the first pair is the .htm file and subsequent pairs are the 
external .js files. Each URL is expressed as an absolute file URL. 

• i sTempFi 1 es is a Boolean indicating whether the instrumented files should be 
tracked and deleted the next time the debugger is launched, or when 
Dreamweaver shuts down. 

• browserName is optional; it specifies the name of the target browser as defined 
in the Preview settings in Browser Preferences. It can also be 'primary' or 
'secondary . If omitted, the primary browser is used by default. 

Returns 

Nothing. 
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Keyboard functions 

Keyboard functions mimic document navigation tasks that are accomplished by 
pressing the arrow, Backspace, Delete, Page Up, and Page Down keys. In addition 
to such general arrow and key methods as arrowl_eft( ) and backspaceKey ( ), 
Dreamweaver also provides methods for moving to the next or previous word 
or paragraph, and moving to the end of line or document or start of the line 
or document. 

dom,arrowDown{) 

Availability 

Dreamweaver 3.0 

Description 

Moves the insertion point down the specified number of times. 
Arguments 

{nTimes}, {bShi ftlsDown} 

• nTimes is the number of times the insertion point should be moved down. If 
this argument is omitted, the default is 1 . 

• bShi ftlsDown is a Boolean value indicating whether to extend the selection. If 
this argument is omitted, the default is fal se. 

Returns 

Nothing. 

Enabler 

None. 

dom,arrovvLeft() 

Availability 

Dreamweaver 3.0 

Description 

Moves the insertion point left the specified number of times. 
Arguments 

(nTimes}, (bShi ftlsDown} 

• nTimes is the number of times the insertion point should be moved left. If this 
argument is omitted, the default is 1 . 

• bShi ftlsDown is a Boolean value indicating whether to extend the selection. If 
this argument is omitted, the default is false. 



308 Chapter 20 



Returns 

Nothing. 

Enabler 

None. 

dom,arrovvRight{) 

Availability 

Dreamweaver 3.0 

Description 

Moves the insertion point right the specified number of times. 
Arguments 

{nTimes}, (bShi ftlsDown} 

• nTimes is the number of times the insertion point should be moved right. 
If this argument is omitted, the default is 1 . 

• bShi ftlsDown is a Boolean value indicating whether to extend the selection. 
If this argument is omitted, the default is f a 1 se. 

Returns 

Nothing. 

Enabler 

None. 

dom.arrowUpO 

Availability 

Dreamweaver 3-0 

Description 

Moves the insertion point up the specified number of times. 
Arguments 

(nTimes}, {bShi ftlsDown} 

• nTimes is the number of times the insertion point should be moved up. If this 
argument is omitted, the default is 1 . 

• bShi ftlsDown is a Boolean value indicating whether to extend the selection. If 
this argument is omitted, the default is false. 

Returns 

Nothing. 

Enabler 

None. 
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dom.backspaceKey() 

Availability 

Dreamweaver 3.0 

Description 

Equivalent to pressing the Backspace key the specified number of times. The 
exact behavior differs depending on whether there is a current selection or just an 
insertion point. 

Arguments 

{nTi mes } 

nTi mes is the number of times a Backspace operation should occur. If omitted, 
the default is 1 . 

Returns 

Nothing. 

Enabler 

None. 

dom.ddeteKeyQ 

Availability 

Dreamweaver 3.0 

Description 

Equivalent to pressing the Delete key the specified number of times. The exact 
behavior differs depending on whether there is a current selection or just an 
insertion point. 

Arguments 

(nTi mes } 

nTi mes is the number of times a Delete operation should occur. If omitted, the 
default is 1 . 

Returns 

Nothing. 

Enabler 

None. 
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dom.endOfDocumentQ 

Availability 

Dreamweaver 3.0 

Description 

Moves the insertion point to the end of the document (that is, after the last visible 
content in the Document window, or after the closing HTML tag in the Code 
inspector, depending on which window has focus). 

Arguments 

{bShiftlsDown} 

bSh 1 ftlsDown is a Boolean value indicating whether to extend the selection. 
If omitted, the default is fal se. 

Returns 

Nothing. 

Enabler 

None. 

dom.endOfLineQ 

Availability 

Dreamweaver 3.0 

Description 

Moves the insertion point to the end of the line. 

Arguments 

{bShiftlsDown} 

bSh 1 ftlsDown is a Boolean value indicating whether to extend the selection. 
If omitted, the default is fal se. 

Returns 

Nothing. 

Enabler 

None. 
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dom.nextFaragraphQ 

Availability 

Dreamweaver 3.0 

Description 

Moves the insertion point to the beginning of the next paragraph (or skips 
multiple paragraphs if nTimes is greater than 1). 

Arguments 

{nTimes}, {bShi ftlsDown} 

• nTimes is the number of paragraphs ahead the insertion point should jump. 
If this argument is omitted, the default is 1 . 

• bSh i ftlsDown is a Boolean value indicating whether to extend the selection. 
If this argument is omitted, the default is false. 

Returns 

Nothing. 

Enabler 

None. 

dom,nextWord() 

Availability 

Dreamweaver 3.0 

Description 

Moves the insertion point to the beginning of the next word (or skips multiple 
words if nTimes is greater than 1). 

Arguments 

{nTimes}, {bShi ftlsDown} 

• nTimes is the number of words ahead the insertion point should jump. If this 
argument is omitted, the default is 1 . 

• bSh i ftlsDown is a Boolean value indicating whether to extend the selection. 
If this argument is omitted, the default is false. 

Returns 

Nothing. 

Enabler 

None. 
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dom.pageDownQ 

Availability 

Dreamweaver 3.0 

Description 

Moves the insertion point down one page (equivalent to pressing Page Down). 
Arguments 

(nTimes}, {bShi ftlsDown} 

• nTimes is the number of pages down the insertion point should move. If this 
argument is omitted, the default is 1 . 

• bShi ftlsDown is a Boolean value indicating whether to extend the selection. 
If this argument is omitted, the default is f a 1 se. 

Returns 

Nothing. 

Enabler 

None. 

dom.pagelipO 

Availability 

Dreamweaver 3.0 

Description 

Moves the insertion point up one page (equivalent to pressing Page Up). 
Arguments 

{nTimes}, (bShi ftlsDown} 

• nTimes is the number of pages up the insertion point should move. If this 
argument is omitted, the default is 1 . 

• bShi ftlsDown is a Boolean value indicating whether to extend the selection. 
If this argument is omitted, the default is f a 1 se. 

Returns 

Nothing. 

Enabler 

None. 
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dom.previousFaragraphQ 

Availability 

Dreamweaver 3.0 

Description 

Moves the insertion point to the beginning of the previous paragraph (or skips 
multiple paragraphs if nTimes is greater than 1). 

Arguments 

{nTimes}, {bShi ftlsDown} 

• nTimes is the number of paragraphs back the insertion point should jump. 
If this argument is omitted, the default is 1 . 

• bSh i ftlsDown is a Boolean value indicating whether to extend the selection. 
If this argument is omitted, the default is false. 

Returns 

Nothing. 

Enabler 

None. 

dom,previousWord() 

Availability 

Dreamweaver 3.0 

Description 

Moves the insertion point to the beginning of the previous word (or skips 
multiple words if nTimes is greater than 1). 

Arguments 

{nTimes}, {bShi ftlsDown} 

• nTimes is the number of words back the insertion point should jump. If this 
argument is omitted, the default is 1 . 

• bSh i ftlsDown is a Boolean value indicating whether to extend the selection. 
If this argument is omitted, the default is false. 

Returns 

Nothing. 

Enabler 

None. 
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dom.startOfDocument() 

Availability 

Dreamweaver 3.0 

Description 

Moves the insertion point to the beginning of the document (that is, before the 
first visible content in the Document window, or before the opening HTML tag in 
the Code inspector, depending on which window has focus). 

Arguments 

{bShiftlsDown} 

bSh 1 ftlsDown is a Boolean value indicating whether to extend the selection. 
If omitted, the default is fal se. 

Returns 

Nothing. 

Enabler 

None. 

dom.startOfLine() 

Availability 

Dreamweaver 3.0 

Description 

Moves the insertion point to the beginning of the line. 

Arguments 

{bShiftlsDown} 

bSh 1 ftlsDown is a Boolean value indicating whether to extend the selection. 
If omitted, the default is fal se. 

Returns 

Nothing. 

Enabler 

None. 
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mapKeyCodeloCharO 

Description 

Takes a key code as retrieved from the event object's key Code field and translates it 
to a character. You should first check to see if the key code is a special key, such as 
HOME, PGUP, and so on. If the key code is not a special key, then this method 
should be used to translate it to a character code suitable for display to the user. 

Arguments 

keyCode 

key Code is the key code to translate to a character. 

Returns 

Nothing. 



Layer and smage map functions 

Layer and image map functions handle aligning, resizing, and moving layers 
and image map hotspots. The function description indicates if it applies to layers 
or to hotspots. 

dom,aHgn(} 

Availability 

Dreamweaver 3.0 

Description 

Aligns the selected layers or hotspots left, right, top, or bottom. 

Arguments 

a 1 i gnDi recti on 

a 1 i gnDi recti on is the edge on which the layers or hotspots should be aligned — 
"1 eft", "right", "top", or "bottom". 

Returns 

Nothing. 

Enabler 

dotn.canAl ign( ) 
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dom.arrangeQ 

Availability 

Dreamweaver 3.0 

Description 

Moves the selected hotspots in the specified direction. 

Arguments 

toBackOrFront 

toBackOrFront is the direction in which the hotspots should be moved — 
"front" or "back". 

Returns 

Nothing. 

Enabler 

dom.canArrange( ) 
dom.makeSizesEquaI() 

Availability 

D ream weaver 3 . 0 

Description 

Makes the selected layers or hotspots equal in height, width, or both. The last 
layer or hotspot selected is the guide. 

Arguments 

bhioriz, bVert 

• bHoriz is a Boolean value indicating whether to resize the layers or 
hotspots horizontally. 

• bVert is a Boolean value indicating whether to resize the layers or 
hotspots vertically. 

Returns 

Nothing. 

Enabler 

None. 
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dom^moveSeSectionByQ 

Availability 

Dreamweaver 3.0 

Description 

Moves the selected layers or hotspots by the specified number of pixels 
horizontally and vertically. 

Arguments 

x, y 

• x is the number of pixels the selection should be moved horizontally. 

• y is the number of pixels the selection should be moved vertically. 

Returns 

Nothing. 

Enabler 

None. 

dom,res§zeSelect{'onBy() 

Availability 

Dreamweaver 3.0 

Description 

Resizes the currently selected layer or hotspot. 
Arguments 

left, top, bottom, right 

• / eft is the new position of the left boundary of the layer or hotspot. 

• top is the new position of the top boundary of the layer or hotspot. 

• bottom is the new position of the bottom boundary of the layer or hotspot. 

• right is the new position of the right boundary of the layer or hotspot. 

Returns 

Nothing. 

Enabler 

None. 
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Example 

If the selected layer has the Left, Top, Width, and Height properties shown, 
calling d w. get Document DOM ( ).resizeSelectionBy(-10,-30,30,10) would be 
equivalent to resetting Left to 40, Top to 20, Width to 240, and Height to 240. 
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dom.setLayerTagO 

Availability 

D ream weaver 3 . 0 

Description 

Specifies the HTML tag that defines the selected layer or layers. 

Arguments 

tagName 

tagName must be "1 ayer", "i 1 ayer", "di v", or "span". 

Returns 

Nothing. 

Enabler 

None. 
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Library and template functions 

Library and template functions manage operations related to library items and 
templates, such as creating, updating, and breaking links between a document and 
a template or library item. Methods of the d reamwea ver . libraryPalette object 
either control or act on the selection in the Library panel (programmed into the 
API as "palette"), not in the current document. Likewise, methods of the 
d reamwea ver . tempi atePal ette object control or act on the selection in the 
Template panel. 



dom.appiyTemplateQ 

Availability 

Dreamweaver 3.0 

Description 

Applies a template to the current document. If no argument is supplied, the Select 
Template dialog box appears. This function is valid only for the active document. 

Arguments 

{ tempi ateURL}, bMai ntai nil nk 

• tempi ateURL is the path to a template in the current site, expressed as a 
file:// URL. 

• b Ma i ntai nLink is a Boolean indicating whether to maintain the link to the 
original template (true) or not (fal se). 

Returns 

Nothing. 

Enabler 

dom.canApplyTempl ate( ) 
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dom.detachFromUbraryO 

Availability 

Dreamweaver 3.0 

Description 

Detaches the selected instance of a library item from its associated LB I file by 
removing the locking tags from around the selection. This function is equivalent 
to clicking Detach from Original in the Property inspector. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

dom.detachFromTernplateQ 

Availability 

Dreamweaver 3.0 

Description 

Detaches the current document from its associated template. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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dom.getAttachedTemplateQ 

Availability 

Dreamweaver 3.0 

Description 

Gets the path of the template that is associated with the document. 

Arguments 

None. 

Returns 

A string containing the path of the template, expressed as a file:// URL. 

Enabler 

None. 

dom.getEditableReg[onUst() 

Availability 

D ream weaver 3 . 0 

Description 

Gets a list of all the editable regions in the body of the document. 

Arguments 

None. 

Returns 

An array of element nodes. 

Enabler 

None. 

Example 

See "dom.getSelectedEditableRegion()" on page 324. 
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dom.getSsUbraryDocumentQ 

Availability 

Dreamweaver 3.0 

Description 

Determines whether the document is a library item. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the document is an LBI file. 

Enabler 

None. 

dom.getSsTemplateDocimientQ 

Availability 

D ream weaver 3 . 0 

Description 

Determines whether the document is a template. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the document is a DWT file. 

Enabler 

None. 
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dom.getSelectedEd[tableRegaon() 

Availability 

Dreamweaver 3.0 

Description 

If the selection or insertion point is inside an editable region, gets the position of 
the editable region among all others in the body of the document. 

Arguments 

None. 

Returns 

An index into the array returned by dom. get Ed i tabl eRegi on Li st( ). 

Enabler 

None. 

Example 

The following code shows a dialog box containing the contents of the selected 
editable region: 

var theDOM = dw . getDocumentDOM( ) ; 
var edRegs = theDOM . getEdi tabl eRegi onLi st( ) ; 
var selReg = theDOM . getSel ectedEdi tabl eRegi on () ; 
al ert( edRegs [s el Reg] .innerHTML) ; 

domJnsertLabraryStemO 

Availability 

Dreamweaver 3.0 

Description 

Inserts an instance of a library item into the document. 

Arguments 

/ / braryltemURL 

1 i braryltemURL is the path to an LBI file, expressed as a file:// URL. 

Returns 

Nothing. 

Enabler 

None. 
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dom.markSeSectionAsEditableO 

Availability 

Dreamweaver 3.0 

Description 

Displays the New Editable Region dialog box. When the user clicks New Region, 
Dreamweaver marks the selection as editable and leaves any text as is. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dom.canMarkSelectionAsEditableO 

dom.newEditableRegionQ 

Availability 

D ream weaver 3 . 0 

Description 

Displays the New Editable Region dialog box. When the user clicks New Region, 
Dreamweaver inserts the name of the region, surrounded by braces ({ }), into the 
document at the insertion point location. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dom . canMakeNewEdi tabl eRegi on ( ) 
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dom.removeEclitableRegionO 

Availability 

Dreamweaver 3.0 

Description 

Removes an editable region from the document. If the editable region 
contains any content, the content is preserved — only the editable region 
markers are removed. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dom . can Remove Ed i tabl eRegion( ) 



dom,updateCurrentPage() 

Availability 

Dreamweaver 3.0 

Description 

Updates the document's library items, templates, or both. This function is valid 
only for the active document. 

Arguments 

{typeOfUpddte} 

typeOfilpdate, if supplied, must be "1 i brary ", "tempi ate", or "both". If 
omitted, the default is "both \ 

Returns 

Nothing. 

Enabler 

None. 
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d reamweaver. u pdatePages() 

Availability 

Dreamweaver 3.0 

Description 

Opens the Update Pages dialog box and selects the specified options. 

Arguments 

{typeOfUpdate} 

typeOfilpdate must be "1 ibrary", "tempi ate", or "both". If the argument is 
omitted, it defaults to " both " . 

Returns 

Nothing. 

Enabler 

None. 

dreamweaver D templatePaiette,newBiankTemplate{) 

Availability 

Dreamweaver 3.0 

Description 

Creates a new template. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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Menu functions 



Menu functions deal with optimizing and reloading the menus in Dreamweaver. 

The dreamweaver . getMenuNeedsUpdati ng( ) and 

dreamweaver. not ify Menu UpdatedO functions are designed specifically to 
prevent unnecessary update routines from running on the dynamic menus that are 
built into Dreamweaver. 



dreamweaver.getyenuNeedsUpdathig{) 

Availability 

Dreamweaver 3.0 

Description 

Checks whether the specified menu needs to be updated. 

Arguments 

menuld 

menu Id is a string containing the value of the i d attribute for the menu item (as 
specified in the menus .xml file). 

Returns 

A Boolean value indicating whether the menu needs to be updated. This function 
returns false only if dreamweaver . noti fyMenuUpdated ( ) has been called with 
this menuld, and the return value of menui 1 stFuncti on has not changed since 
that time. See dreamweaver . noti fyMenuUpdated ( ) for more information. 

Enabler 

None. 
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dreamweaver.notifyyenuUpdatedO 

Availability 

Dreamweaver 3.0 

Description 

Notifies Dreamweaver when the specified menu needs to be updated. 
Arguments 

menuld, menuLi stFuncti on 

• menu Id is a string containing the value of the i d attribute for the menu item (as 
specified in the menus .xml file). 

• menu Li stFuncti on must be one of the following strings: 
"dw. ess Sty 1 ePal ette . get Sty 1 es( ) 

"dw. get Document DOM ( ) . get Frame Names ( ) ", 

"dw. get Document DOM ( ) . get Ed i tabl eRegi on Li st 

"dw. get Browser Li st( ) ", "dw . get Recent Fi 1 e Li st( ) ", 

"dw. getTransl a tor Li st( ) "dw . get Font Li st( ) 

"dw. get Document Li st( ) ", "dw . html Sty 1 ePal ette . getStyl es ( ) or 

"si te . getSi tes( ) ". 

Returns 

Nothing. 

Enabler 

None. 

d reamweaver, reload Men us() 

Availability 

D ream weaver 3 . 0 

Description 

Reloads the entire menu structure from the menus.xml file in the 
Configuration folder. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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Path functions 

Path functions get and manipulate the paths to various files and folders on the 
users hard disk. These functions determine the path to the root of the site in 
which the current document resides, convert relative paths to absolute URLs, 
and more. 

dreamweaver\getConf[gurat^onPath() 

Availability 

Dreamweaver 2.0 

Description 

Gets the path to the Configuration folder, expressed as a file:// URL. 

Arguments 

None. 

Returns 

A string containing the path to the Configuration folder. 

Enabler 

None. 

Example 

This function is useful when referencing other extension files, which are all 
stored in the Configuration folder inside the Dreamweaver application folder. 
For example: 

var sortCmd = dreamweaver . getConf i gurati onPath ( ) + "/Commands/^ 
Sort Table.htm" 

var sortDOM = dreamweaver . getDocumentDOM( sortCmd ) ; 
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dreamweaver.gefDocurr&entFathQ 



Availability 

D ream weaver 1 . 2 

Description 

Gets the path of the specified document, expressed as a file:// URL. This function 
is equivalent to calling dreamweaver . getDocumentDOM( ) and then reading the 
URL properly of the return value. 

Arguments 

sourceDoc 

sourceDoc must be "document", "parent", "parent . frames [number] 
or "parent . frames [ ' franieNanie' ] ". document specifies the document 
that has the focus and contains the current selection, "parent" specifies 
the parent frameset (if the currently selected document is in a frame), and 
"parent . frames [ number] " and "parent . frames [ ' frameName' ] " specify a 
document that is in a particular frame within the frameset containing the 
current document. 

Returns 

One of the following values: 

• A string containing the URL of the specified document if the file was saved. 

• An empty string if the file was not saved. 

Enabler 

None. 
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dreamweaver.gefSiteRootO 

Availability 

Dreamweaver 1.2 

Description 

Gets the local root folder (as specified in the Site Definition dialog box) for the 
site associated with the currently selected document, expressed as a file:// URL. 

Arguments 

None. 

Returns 

One of the following values: 

• A string containing the URL of the local root folder of the site within which 
the file was saved. 

• An empty string if the file is not associated with a site. 

Enabler 

None. 

d rearnweaver. reiat i veToAbsoi ut eU R L() 

Availability 

Dreamweaver 2.0 

Description 

Given a relative URL and a point of reference (either the path to the current 
document or the site root), converts the relative URL to an absolute (file://) URL. 

Arguments 

relURL, docPath, siteRoot 

• re 1URL is the URL to be converted. 

• docPa th is the path to a document on the users disk (for example, the current 
document), expressed as a file:// URL or an empty string if re 1 URL is a root- 
relative URL. 

• siteRoot is the path to the site root, expressed as a file:// URL or an empty 
string if re 1 URL is a document-relative URL. 
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Returns 

An absolute URL string. The return value is generated as follows: 

• If re 7 URL is an absolute URL, no conversion takes place, and the return value 
is the same as r el URL. 

• If re 1 URL is a document-relative URL, the return value is the combination of 

docPath + relURL. 

• If re 1 URL is a root-relative URL, the return value is the combination of 

siteRoot + relURL. 

Enabler 

None. 

Quick Tag Editor functions 

Quick Tag Editor functions navigate through the tags within and surrounding the 
current selection. They remove any tag in the hierarchy, wrap the selection inside 
a new tag, and show the Quick Tag Editor to let the user edit specific attributes 
for the tag. 

dom.seiectChildQ 

Availability 

Dreamweaver 3.0 

Description 

Selects a child of the current selection. Calling this function is equivalent to 
selecting the next tag to the right in the tag selector at the bottom of the 
Document window. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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dorTLseSectFarentQ 

Availability 

Dreamweaver 3.0 

Description 

Selects the parent of the current selection. Calling this function is equivalent 
to selecting the next tag to the left in the tag selector at the bottom of the 
Document window. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 



dom.stnpTagQ 

Availability 

Dreamweaver 3.0 

Description 

Removes the tag from around the current selection, leaving the contents, if 
any. If the selection contains more than one tag or no tags, Dreamweaver 
reports an error. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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dom.wrapTagO 

Availability 

Dreamweaver 3.0 

Description 

Wraps the specified tag around the current selection. If the selection is 
unbalanced, Dreamweaver reports an error. 

Arguments 

startTag 

sta rtTag is the source associated with the opening tag. 

Returns 

Nothing. 

Enabler 

None. 

Example 

The following code wraps a link around the current selection: 

var theDOM = dw . getDocumentDOM( ) ; 
var theSel = theDOM . getSel ectedNode( ) ; 
if (theSel .nodeType = = Node . TEXO0DE ) { 
theDOM. wrapTag( ' <a href=" foo . html ">' ) ; 

} 

dreamweaver.showQidcklagEditorO 

Availability 

Dreamweaver 3.0 

Description 

Displays the Quick Tag Editor for the current selection. 

Arguments 

{nearblhat}, {mode} 

• nearblhat, if specified, must be either "selection" or "tag sel ector". The 
default value if this argument is omitted is "selection". 

• mo de s if specified, must be "def a ul t", "wrap", "i nsert", or "edi t". 

If mode is "defaul t" or omitted, Dreamweaver uses heuristics to determine 
the mode to use for the current selection, mode is ignored if neark/ha t is 
"tag selector". 

Returns 

Nothing. 

Enabler 

None. 
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Report functions 

Report functions provide acces to the Dreamweaver reporting features so you can 
initiate, monitor and customize the the reporting process. For more information, 
see "Reports" on page 55- 

dreamweaverjsReportmgO 

Availability 

Dreamweaver 4.0 

Description 

Checks to see if a reporting process is currently running. 

Arguments 

None. 

Returns 

Boolean value indicating whether a process is running (true) or not (f al se). 

d reamweaver.showReportsD sal og () 

Availability 

Dreamweaver 4.0 

Description 

Opens the Reports dialog box. 

Arguments 

None. 

Returns 

Nothing. 
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dreamweaver.resuSts.setResultDataO 

Availability 

Dreamweaver 4.0 

Description 

Adds new entries to the results window that is active during the reporting process. 
If a report is not being generated, then this function will have no effect. 

Arguments 

strFi lePath, strlcon, strDi spl ay, strDesc, { i Line No}, { iStartSel }, 
{iEndSel} 

• strFi 1 ePa th is a fully qualified URL to the file. 

• strlcon is the fully qualified path to the icon to use for the results entry. You 
can reference built-in icons by specifying a number between 1 and 10. 

• strDi spl ay is a string to display in the first column; this is usually a file name. 

• st rDes c is a description to go along with the entry. 

• / L ineNo is the number of lines in the file, if specified. 

• iStartSe 1 is the start of the offset into the file, if specified. 

• lEndSe 1 is the end of offset into the file; this is required only if iStartSel 
is specified. 

Returns 

Nothing. 
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Results window functions 



Results window functions allow you to create a window displaying formatted data. 
Use these functions to create custom windows similar to the output from the 
JavaScript Debugger window or the Report Results window. 

dreamweaver D createResu]tsWEndow() 

Availability 

Dreamweaver 4.0 

Description 

Creates a new Results window and returns a JavaScript object reference to the 
window. 

Arguments 

strName, arrColumns 

• st rName is the string to use for the window's title. 

• arrCo 1 umns is an array of column names to use in the list control. 
Returns 

An object reference to the created window. 

resWgn.adcHtemQ 

Availability 

Dreamweaver 4.0 

Description 

Adds a new item to the Results window. 
Arguments 

strlcon, strDesc, iStartSel, iEndSel, colNdata 

• strlcon is an icon to display. Specify 0 for no icon. 

• st rDes c is a detailed description of code font item. Specify code font if there is 
no description. 

• i StartSel is the start of selection offset in the file. Specify null if not used. 

• / EndSe 1 is the end of selection offset in the file. Specify code font if not used. 

• col Ndata is a string to use for each column. 
Returns 

A Boolean value, true if the item was added successfully, fal se otherwise. 
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resWm.setCaHbackCommandsQ 

Availability 

Dreamweaver 4.0 

Description 

Tells the Results window on which commands to call the processFile( ) 
method. If this function is not called, the command that created the Results 
window is called. 

Arguments 

arrCmdNames 

a rrCmd 'Names is an array of command names on which to call the 
process Fi 1 e( ) method. 

Returns 

Nothing. 

resWgn B setCoIumnW§dths{) 

Availability 

Dreamweaver 4.0 

Description 

Sets the width of each column. 

Arguments 

arrWidth 

arrk/idth is an array of integers representing the widths to use for each column in 
the control. 

Returns 

Nothing. 
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resWsn.setRleLJstQ 

Availability 

Dreamweaver 4.0 

Description 

Gives the Results window a list of files, directories, or both to call a set of 
commands to process. 

Arguments 

arrFil ePaths, bRecursive 

• arrFi 1 ePa ths is an array of file or folder paths to iterate through. 

• bRecursive is a. Boolean value indicating whether the iteration should be 
recursive (true) or not (fal se). 

Returns 

Nothing. 

resWsrLsetTltleQ 

Availability 

Dreamweaver 4.0 

Description 

Sets the title of the window. 

Arguments 

strTi tie 

strTi tie is the new name of the floating panel. 

Returns 

Nothing. 

resWsn.startProcessmgQ 

Availability 

Dreamweaver 4.0 

Description 

Starts processing the file. 

Arguments 

None. 

Returns 

Nothing. 
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resWsn.stopProcessingO 

Availability 

Dreamweaver 4.0 

Description 

Stops processing the file. 

Arguments 

None. 

Returns 

Nothing. 



Selection functions 

Selection functions get and set the selection in open documents. For 
information on getting or setting the selection in the Site window, see 
"Site functions" on page 348. 



dom,getSe!ectedNode() 

Availability 

Dreamweaver 3.0 

Description 

Gets the selected node. This function is equivalent to calling 
dom. getSel ecti on( ) and then passing the return value to 

dom.off setsToNode( ). 

Arguments 

None. 

Returns 

The tag, text, or comment object that completely contains the specified range 
of characters. 

Enabler 

None. 
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dom.getSelect§on{) 

Availability 

Dreamweaver 3.0 

Description 

Gets the selection, expressed as character offsets into the document's HTML 
source code. 

Arguments 

bAl 1 owMul ti pi e 

bA 1 lowMu 1 1 ip 7 e is a Boolean value indicating whether the function should 
return multiple offsets if more than one table cell, image map hotspot, or layer is 
selected. If this argument is omitted, it defaults to f al se. 

Returns 

For simple selections, an array containing two integers. The first integer is the 
character offset of the beginning of the selection. The second integer is the 
character offset of the end of the selection. If the two numbers are the same, then 
the current selection is an insertion point. 

For complex selections (multiple table cells, multiple layers, or multiple image 
map hotspots), an array containing 2n integers, where n is the number of selected 
items. The first integer in each pair is the character offset of the beginning of the 
selection (including the opening TD, DI V, SPAN, LAYER, I LAYER, or MAP tag); the 
second integer in each pair is the character offset of the end of the selection 
(including the closing TD, DIV, SPAN, LAYER, I LAYER, or MAP tag). If multiple table 
rows are selected, the offsets of each cell in each row are returned. The selection 
never includes the TR tags. 

Enabler 

None. 
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dom.nodeToOffsets() 



Availability 

Dreamweaver 3.0 

Description 

Gets the position of a specific node in the DOM tree, expressed as character 
offsets into the document's HTML source code. Valid for any document on a 
local drive. 

Arguments 

node 

node must be a tag, comment, or range of text that is a node in the tree returned 

by dreamweaver . ge t Document DOM ( ). 

Returns 

An array containing two integers. The first integer is the character offset of the 
beginning of the tag, text, or comment; the second integer is the character offset 
of the end of the node, from the beginning of the HTML document. 

Enabler 

None. 

Example 

The following code selects the first image object in the current document: 

var theDOM = dw . getDocumentDOM( ) ; 

var thelmg = theDOM . i mages [0] ; 

var offsets = theDom . nodeToOff sets ( thelmg ) ; 

theDom. set Sel ecti on (offsets [0] , offsets[l]); 
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dom,offsetsToNode() 

Availability 

Dreamweaver 3.0 

Description 

Gets the object in the DOM tree that completely contains the range of characters 
between the specified begin and end points. Valid for any document on a 
local drive. 

Arguments 

offsetBegi n 3 offsetEnd 

The arguments are the begin and end points, respectively, of a range of characters, 
expressed as character offsets from the beginning of the document's HTML 
source code. 

Returns 

The tag, text, or comment object that completely contains the specified range 
of characters. 

Enabler 

None. 

Example 

The following code displays an alert if the selection is an image: 

var offsets = dom . getSel ecti on ( ) ; 

var theSel ecti on = dreamweaver . of fsetsToNode(of fsets[0] , -< 
offsets[l]) ; 

if (theSelection.nodeType == Node . ELEMENT_N0DE && - 
theSel ecti on . tagName == ' I MG ' ) { 

alert('The current selection is an image.'); 

} 
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dom.seSectAHQ 

Availability 

Dreamweaver 3.0 

Description 

Performs a Select All operation. 

Note: In most cases this function selects all content in the active document. In some cases 
(for example, when the insertion point is inside a table), however, it selects only part of the 
active document. To set the selection to the entire document, use dom. setSel ecti on( ). 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

dom,selectTable() 

Availability 

Dreamweaver 3.0 

Description 

Selects an entire table. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dotn.canSel ectTabl e( ) 
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dom.setSelectedNodeQ 

Availability 

Dreamweaver 3.0 

Description 

Sets the selected node. This function is equivalent to calling 
dom. nodeToOf fsets( ) and then passing the return value to 

dom . setSel ecti on ( ) . 

Arguments 

node, {bSel ectlnside), {bJumpToNode} 

• node is a text, comment, or element node in the document. 

• bSe 1 ectlnsi de is a Boolean value indicating whether to select the 

i nnterHTML of the node. This argument is relevant only if node is an element 
node, and it defaults to fal se if omitted. 

• bJumpToNode is a Boolean value indicating whether to scroll the Document 
window, if necessary, to make the selection visible. If omitted, this argument 
defaults to fal se. 

Returns 

Nothing 

Enabler 

None. 
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dom.setSelectaon() 

Availability 

Dreamweaver 3.0 

Description 

Sets the selection in the document. 
Arguments 

offsetBegin, offsetEnd 

The arguments are the begin and end points, respectively, for the new selection, 
expressed as character offsets into the document's HTML source code. If the two 
numbers are the same, the new selection is an insertion point. If the new selection 
is not a valid HTML selection, it is expanded to include the characters in the first 
valid HTML selection. For example, if offsetBegin and off set End define the 
range SRC=" my Image . gi f " within < I MG SRO"my Image . gi f ">, the selection 
expands to include the entire IMG tag. 

Returns 

Nothing. 

Enabler 

None. 

dreamweaver.seleetAyC) 

Availability 

Dreamweaver 3.0 

Description 

Performs a Select All operation in the active Document window or the Site 
window; or, on the Macintosh, the edit field that has focus in a dialog box or 
floating panel. 

Note: If the operation takes place in the active document, in most cases it selects all 
content in the active document. In some cases (for example, when the insertion point is 
inside a table), however, it selects only part of the active document. To set the selection to 
the entire document, use dom. setSel ecti on( ). 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamweaver . canSel ectAl 1 ( ) 
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Site functions 



Site functions handle operations related to files in the site files or site map. These 
functions create links between files; get, put, check in, and check out files; select 
and deselect files; create and remove files; get information about the sites that the 
user has defined; and more. 

dreamweaverJoadSitesFromPrefsQ 

Availability 

Dreamweaver 4.0 

Description 

Loads the site information for all sites from the system registry (Windows) or the 
Dreamweaver preferences file (Macintosh) into Dreamweaver. If a site is 
connected to a remote server when this function is called, the site will be 
automatically disconnected. 

Arguments 

None. 

Returns 

Nothing. 

dreamweaver 0 saveS§tesToPrefs() 

Availability 

Dreamweaver 4.0 

Description 

Saves all information for each site the user has defined to the system registry 
(Windows) or the Dreamweaver preferences file (Macintosh). 

Arguments 

None. 

Returns 

Nothing. 
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site.addLmkToExistmgFneQ 

Availability 

Dreamweaver 3.0 

Description 

Opens the Select HTML File dialog box to let the user select a file, and then 
creates a link from the selected document to that file. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

si te . canAddLi nk( ) 
slte,addUnkToNewFile{) 

Availability 

D ream weaver 3 • 0 

Description 

Opens the Link to New File dialog box to let the user specify details for the new 
file, and then creates a link from the selected document to that file. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

si te . canAddLi nk( ) 

sitexanEdBtColumnsO 

Description 

Determines whether or not a site exists. 

Arguments 

None. 

Returns 

true if a site exists. 
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sitexhangeLsnkSatewideQ 

Availability 

Dreamweaver 3.0 

Description 

Opens the Change Link Sitewide dialog box. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

sitexhangeUnkQ 

Availability 

D ream weaver 3 . 0 

Description 

Opens the Select HTML File dialog box to let the user select a new file for 
the link. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

si te . canChangeLi nk( ) 
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sitexhecklnQ 

Availability 

Dreamweaver 3.0 

Description 

Checks in the selected files and handles dependent files in one ofthe 
following ways: 

• If the user selected Prompt on Put/Check In in the Site FTP preferences, the 
Dependent Files dialog box appears. 

• If the user previously selected the Don't Show Me Again option in the 
Dependent Files dialog box and then clicked Yes, dependent files are uploaded 
and no dialog box appears. 

• If the user previously selected the Don't Show Me Again option in the 
Dependent Files dialog box and then clicked No, dependent files are not 
uploaded and no dialog box appears. 

Arguments 

siteOrURL 

s 1 teOrURL must be the keyword "site", indicating that the function should act 
on the selection in the Site window or on the URL for a single file. 

Returns 

Nothing. 

Enabler 

si te . canCheckIn( ) 

sitexheckLinksQ 

Availability 

Dreamweaver 3-0 

Description 

Opens the Link Checker dialog box and checks links in the specified files. 

Arguments 

scopeOfCheck 

scopeOfCheck specifies where links will be checked. It must be "document", 
"sel ection", or "site". 

Returns 

Nothing. 

Enabler 

None. 
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sitexheckOutQ 

Availability 

Dreamweaver 3.0 

Description 

Checks out the selected files and handles dependent files in one of the 
following ways: 

• If the user selected Prompt on Get/Check Out in the Site FTP preferences, the 
Dependent Files dialog box appears. 

• If the user previously selected the Don't Show Me Again option in the 
Dependent Files dialog box and then clicked Yes, dependent files are 
downloaded and no dialog box appears. 

• If the user previously selected the Don't Show Me Again option in the 
Dependent Files dialog box and then clicked No, dependent files are not 
downloaded and no dialog box appears. 

Arguments 

siteOrURL 

s i teOrURL must be the keyword "site", indicating that the function should act 
on the selection in the Site window or on the URL for a single file. 

Returns 

Nothing. 

Enabler 

si te . canCheckOuK ) 



sitexhecklargetBrowsersQ 

Availability 

Dreamweaver 3-0 

Description 

Runs a target browser check on the selected files. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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site.defsneSitesQ 

Availability 

Dreamweaver 3.0 

Description 

Opens the Define Sites dialog box. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

site.deleteSelectsonQ 

Availability 

D ream weaver 3 . 0 

Description 

Deletes the selected files. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

site.edatCoSumnsQ 

Description 

Displays the Define Sites dialog box with the file view columns section showing. 

Arguments 

None. 

Returns 

Nothing. 
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siteJocatelnSiteQ 

Availability 

Dreamweaver 3.0 

Description 

Locates the specified file or files in the specified pane of the Site window, and 
selects the found files. 

Arguments 

1 ocal OrRemote, siteOrURL 

• / ocal Or Remote must be either "1 ocal " or " remote". 

• s / teOrURL must be the keyword "site", indicating that the function should 
act on the selection in the Site window or on the URL for a single file. 

Returns 

Nothing. 

Enabler 

si te . canLocatelnSi te( ) 

siteirndLinkSourceQ 

Availability 

D ream weaver 3 . 0 

Description 

Opens the file that contains the selected link or dependent file, and highlights the 
text of the link or the reference to the dependent in that file. This function 
operates only on files in the Site Map view. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

si te . canFi rid Li nkSource( ) 



354 Chapter 20 



site.getQ 

Availability 

Dreamweaver 3.0 

Description 

Gets the specified files and handles dependent files in one of the following ways: 

• If the user selected Prompt on Get/Check Out in the Site FTP preferences, the 
Dependent Files dialog box appears. 

• If the user at some point selected the Don't Show Me Again option in the 
Dependent Files dialog box and then clicked Yes, dependent files are 
downloaded and no dialog box appears. 

• If the user at some point selected the Don't Show Me Again option in the 
Dependent Files dialog box and then clicked No, dependent files are not 
downloaded and no dialog box appears. 

Arguments 

siteOrURL 

s i teOrURL must be the keyword "si te ", indicating that the function should act 
on the selection in the Site window or on the UHL for a single file. 

Returns 

Nothing. 

Enabler 

si te . canGet( ) 

site,getCheckOutUser{) 

Availability 

D ream weaver 3 . 0 

Description 

Gets the login and check out name associated with the current site. 

Arguments 

None. 

Returns 

A string containing a login and check out name, if defined, or an empty string if 
check in/check out is disabled. 

Enabler 

None. 

Example 

A call to si te . getCheckOutUser ( ) might return "1 ori (1 ori Laptop) ". If no 
check out name is specified, only the login is returned (for example, " 1 ori "). 
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site.getCheckQutUserForFneQ 

Availability 

Dreamweaver 3.0 

Description 

Gets the login and check out name of the user that has the specified file 
checked out. 

Arguments 

fi leNarne 

fi 1 eNdme is the path to the file being inquired about, expressed as a 
file:// URL. 

Returns 

A string containing the login and check out name of the user that has the file 
checked out, or an empty string if the file is not checked out. 

Enabler 

None. 

Example 

A call to si te . getCheckOutUserForFi 1 e( "f i 1 e : //C : / si tes/avocado8/ 
i ndex . html " ) might return "1 ori ( 1 ori Laptop) ". If no check out name is 
specified, only the login is returned (for example, " 1 ori "). 

site.gefConnectionStateQ 

Availability 

Dreamweaver 3.0 

Description 

Gets the current connection state. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the remote site is connected. 
Enabler 

si te . canConnect( ) 
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site.getCurrentSsteQ 

Availability 

Dreamweaver 3.0 

Description 

Gets the current site. 

Arguments 

None. 

Returns 

A string containing the name of the current site. 

Enabler 

None. 

Example 

If you denned several sites, a call tosite.getCurrentSiteO returns the one that 
is currently showing in the Current Sites List in the Site window. 

site.getFocusQ 

Availability 

D ream weaver 3 . 0 

Description 

Determines which pane of the Site window is in focus. 

Arguments 

None. 

Returns 

One of the following strings: "local", "remote", or "site map". 

Enabler 

None. 
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site.getLmkVissbiHtyQ 

Availability 

Dreamweaver 3.0 

Description 

Checks whether all of the selected links in the site map are visible (that is, not 
marked hidden). 

Arguments 

None. 

Returns 

A Boolean value indicating whether all of the selected links are visible. 

Enabler 

None. 

sitagetSelectionQ 

Availability 

Dreamweaver 3.0 

Description 

Determines which files are currently selected in the Site window. 

Arguments 

None. 

Returns 

An array of strings representing the paths of the selected files and folders, 
expressed as file:// URLs, or an empty array if no files or folders are selected. 

Enabler 

None. 
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site.getSitesQ 

Availability 

Dreamweaver 3.0 

Description 

Gets a list of the defined sites. 

Arguments 

None. 

Returns 

An array of strings representing the names of the defined sites, or an empty array if 
no sites are defined. 

Enabler 

None. 

sitaJrwertSelectionQ 

Availability 

Dreamweaver 3.0 

Description 

Inverts the selection in the site map. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

sitamakeEditableQ 

Availability 

D ream weaver 3 . 0 

Description 

Turns off the read-only flag on the selected files. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

si te . canMakeEdi tabl e( ) 
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site.makeNewDreamweaverFneQ 

Availability 

Dreamweaver 3.0 

Description 

Creates a new Dreamweaver file in the Site window (in the same directory as the 
first selected file or folder). 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

si te . canMakeNewFi 1 eOrFol der( ) 

slte,makeNewFoIder{) 

Availability 

D ream weaver 3 . 0 

Description 

Creates a new folder in the Site window (in the same directory as the first selected 
file or folder). 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

si te . canMakeNewFi 1 eOrFol der( ) 
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site.newHomePageQ 

Availability 

Dreamweaver 3.0 

Description 

Opens the New Home Page dialog box to let the user create a new home page. 
Note: This function operates only on files in the Site Map view. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

site.newSlteQ 

Availability 

D ream weaver 3 . 0 

Description 

Opens the Site Definition Dialog box for a new, unnamed site. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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site.openQ 

Availability 

Dreamweaver 3.0 

Description 

Opens the files that are currently selected in the Site window. If any folders are 
selected, they are expanded in the Site Files view. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

si te . canOpen ( ) 
site„put() 

Availability 

D ream weaver 3 • 0 

Description 

Puts the selected files and handles dependent files in one of the following ways: 

• If the user selected Prompt on Put/Check In in the Site FTP preferences, the 
Dependent Files dialog box appears. 

• If the user previously selected the Don't Show Me Again option in the 
Dependent Files dialog box and then clicked Yes, dependent files are uploaded 
and no dialog box appears. 

• If the user previously selected the Don't Show Me Again option in the 
Dependent Files dialog box and then clicked No, dependent files are not 
uploaded and no dialog box appears. 

Arguments 

siteOrURL 

s i teOrURL must be the keyword "si te ", indicating that the function should act 
on the selection in the Site window or on the UHL for a single file. 

Returns 

Nothing. 

Enabler 

si te . canPut( ) 
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srte.recreateCacheQ 

Availability 

Dreamweaver 3.0 

Description 

Recreates the cache for the current site. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

si te . canRecreateCache( ) 

site.refreshQ 

Availability 

Dreamweaver 3.0 

Description 

Refreshes the file listing on the specified side of the Site window. 

Arguments 

which Side 

whichSide must be "1 ocal ", or " remote". If the site map has focus and 
whi chSi de is "local", the site map refreshes. 

Returns 

Nothing. 

Enabler 

si te . canRef resh( ) 
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site.rerrsoteSsVaHdQ 

Availability 

Dreamweaver 3.0 

Description 

Determines whether the remote site is valid. 

Arguments 

None. 

Returns 

A Boolean value indicating whether a remote site has been defined and, if the 
server type is Local/Network, whether the drive is mounted. 

Enabler 

None. 

sitaremoveLinkQ 

Availability 

Dreamweaver 3.0 

Description 

Removes the selected link from the document above it in the site map. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

si te . canRemoveLi nk( ) 
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site.renameSeSectsonQ 

Availability 

Dreamweaver 3.0 

Description 

Turns the name of the selected file into an edit field, allowing the user to rename 
the file. If more than one file is selected, this function acts on the last selected file. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

sitasaveAsimageQ 

Availability 

Dreamweaver 3.0 

Description 

Opens the Save As dialog box to let the user save the site map as an image. 

Arguments 

fi leType 

file Type is the type of image that should be saved. Valid values for Windows are 
" bmp " and " png " ; valid values for Macintosh are "pi ct " and " j peg " . If the 
argument is omitted, or if the value is not valid on the current platform, the 
default is " bmp " in Windows and " pi ct " on the Macintosh. 

Returns 

Nothing. 

Enabler 

None. 
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site.setectAyQ 

Availability 

Dreamweaver 3.0 

Description 

Selects all files in the active view (either the site map or the site files). 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

site.selectHomePageQ 

Availability 

D ream weaver 3 . 0 

Description 

Opens the Open File dialog box to let the user choose a new home page. 
Note: This function operates only on files in the Site Map view. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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srte.setectMewerQ 

Availability 

Dreamweaver 3.0 

Description 

Selects all files that are newer on the specified side of the Site window. 

Arguments 

which Side 

which Side must be either "1 ocal " or " remote". 

Returns 

Nothing. 

Enabler 

si te . canSel ectNewer( ) 

site,setAsHomePage() 

Availability 

Dreamweaver 3.0 

Description 

Designates the file that is selected in the Site Files view as the home page 
for the site. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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site.setConnectaonStateQ 

Availability 

Dreamweaver 3.0 

Description 

Sets the connection state of the current site. 

Arguments 

bConnected 

bConnected is a Boolean value indicating a connection (true) or not (fal se) to 
the current site. 

Returns 

Nothing. 

Enabler 

None. 



site.setCisrrentS&teQ 

Availability 

Dreamweaver 3.0 

Description 

Opens the specified site in the local pane of the Site window. 

Arguments 

whichSi te 

wh i chSi te is the name of a defined site (as it appears in the Current Sites list in 
the Site window or the Define Sites dialog box). 

Returns 

Nothing. 

Enabler 

None. 

Example 

If three sites are defined (for example, avocado8, dreamcentral, and testsite), a 
call to si te . setCurrentSi te( "dreamcentral " ) ; makes dreamcentral the 
current site. 
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srte,setFocus{) 

Availability 

Dreamweaver 3.0 

Description 

Gives focus to the specified pane of the Site window. If the specified pane is not 
showing, displays the pane and gives it focus. 

Arguments 

which Pane 

which Pane must be one of the following strings: "1 ocal " remote", or 
"site map". 

Returns 

Nothing. 

Enabler 

None. 

sitasetLayoutQ 

Availability 

Dreamweaver 3.0 

Description 

Opens the Site Map Layout pane of the Site Definition dialog box. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

si te . canSetl_ayout( ) 
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site.setLmkVisghiHtyQ 

Availability 

Dreamweaver 3.0 

Description 

Shows or hides the current link. 

Arguments 

bShow 

bShow is a Boolean value indicating whether to remove the Hidden designation 
from the current link. 

Returns 

Nothing. 

Enabler 

None. 

site.setSefectionO 

Availability 

Dreamweaver 3.0 

Description 

Selects files or folders in the active pane in the Site window. 

Arguments 

arrayOfURLs 

arrayOfURLs is an array of strings, each a path to a file or folder in the current 
site, expressed as a file:// URL. 

Note: Leave off the trailing slash (/) when specifying folder paths. 

Returns 

Nothing. 

Enabler 

None. 
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site.synchromzeQ 

Availability 

Dreamweaver 3.0 

Description 

Opens the Synchronize Files dialog box. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

si te . canSynchroni ze( ) 

site.undoCheckOutQ 

Availability 

Dreamweaver 3.0 

Description 

Removes the lock files that are associated with the specified files from the local and 
remote sites, and replaces the local copy of the specified files with the remote copy. 

Arguments 

siteorURL 

s i teorURL must be the keyword "si te indicating that the function should act 
on the selection in the Site window or on the URL for a single file. 

Returns 

Nothing. 

Enabler 

si te.canUndoCheckOut( ) 
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site.viewAsRootQ 

Availability 

Dreamweaver 3.0 

Description 

Temporarily moves the selected file to the top position in the site map. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

si te . canVi ewAsRooK ) 

Source View functions 

Source View functions include operations related to text editing document source 
code (and any subsequent impact on the Design view). The functions in this 
section enable you to add navigational controls to source views within a split 
document view, the Code inspector, and the JavaScript Debugger window. 

dorYtJsDesignViewUpdated() 

Availability 

Dreamweaver 4.0 

Description 

Determines whether or not the Design view and Text view content is synchronized 
for those Dreamweaver operations that require a valid document state. 

Arguments 

None. 

Returns 

t rue if the Design view (WYSIWIG) is synchronized with the text in the Text 
view, fal se otherwise. 



372 Chapter 20 



domJsSebctionValsdQ 

Availability 

Dreamweaver 4.0 

Description 

Determines whether or not a selection is valid, or if it needs to be moved before an 
operation occurs. 

Arguments 

None. 

Returns 

true if the current selection is in a valid piece of code. If the document has not 
been synchronized, returns fal se (because the selection is not updated). 

dom,source D arrowDown{) 

Availability 

Dreamweaver 4.0 

Description 

Moves the insertion point down the source view document, line by line. If content 
is already selected, this function extends the selection line by line. 

Arguments 

InTimes}, {bShi ftlsDown} 

• nTimes is the number of lines the insertion point will move. If nTi mes is 
omitted, the default is 1 . 

• bShi ftlsDown is a Boolean indicating whether or not content is being selected. 
If bShi ftlsDown is true, the content is selected. 

Returns 

Nothing. 
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doiTLSOurce.arrowLeftQ 

Availability 

Dreamweaver 4.0 

Description 

Moves the insertion point to the left in the current line of the Source view. If 
content is already selected, this function extends the selection to the left. 

Arguments 

{nTimesj, {bShi ftlsDown} 

• nTi mes is the number of characters the insertion point will move. If nTi mes is 
omitted, the default is 1 . 

• bSh i ftlsDown is a Boolean indicating whether or not content is being selected. 
If bShi ftlsDown is true, the content is selected. 

Returns 

Nothing. 

dom.source.arrowRsghtQ 

Availability 

Dreamweaver 4.0 

Description 

Moves the insertion point to the right in the current line of the Source view. If 
content is already selected, this function extends the selection to the right. 

Arguments 

{nTimes}, {bShi ftlsDown) 

• nTi mes is the number of characters the insertion point will move. If nTi mes is 
omitted, the default is 1. 

• bSh i ftlsDown is a Boolean indicating whether or not content is being selected. 
If bShi ftlsDown is true, the content is selected. 

Returns 

Nothing. 
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dom.source.arrowUpC) 



Availability 

Dreamweaver 4.0 

Description 

Moves the insertion point up the source view document, line by line. If content is 
already selected, this function extends the selection line by line. 

Arguments 

{nTimesj, (bShi ftlsDown) 

• nTimes is the number of lines the insertion point will move. If nTi mes is 
omitted, the default is 1 . 

• bShi ftlsDown is a Boolean indicating whether or not content is being selected. 
If bShi ftlsDown is true, the content is selected. 

Returns 

Nothing. 



dom.source.ba!anceBracesTextVgew{) 

Availability 

Dreamweaver 4.0 

Description 

Source view extension that enables parentheses balancing. You can call 
dom. source, bal anceBracesTextVi ew( ) to extend a currently highlighted 
selection or insertion point from the start of the surrounding parenthetical 
statement to the end of the statement to balance the following characters: [ ], { } 
and ( ) . Subsequent calls will expand the selection through further levels of 
punctuation nesting. 

Arguments 

None. 

Returns 

Nothing. 
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dom.source.endOfDocumentQ 

Availability 

Dreamweaver 4.0 

Description 

Places the insertion point at the end of the current source view document. If 
content is already selected, this function extends the selection to the end of 
the document. 

Arguments 

bShi ftlsDown 

A Boolean indicating whether or not content is being selected. If bShi ft I sDowin is 
true, the content is selected. 



Returns 

Nothing. 



dom.sQiirce.endOfLmeQ 

Availability 

Dreamweaver 4.0 



Description 

Places the insertion point at the end of the current line. If content is already 
selected, this function extends the selection to the end of the current line. 



Arguments 

bShi ftlsDown 

A Boolean indicating whether or not content is being selected. If bShi f 1 1 sDown is 
true, the content is selected. 

Returns 

Nothing. 
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dom.source.endPageQ 

Availability 

Dreamweaver 4.0 

Description 

Moves the insertion point to the end of the current page or to the end of the next 
page (if the insertion point is already at the end of a page). If content is already 
selected, this function extends the selection page by page. 

Arguments 

{nTimes}, {bShi ftlsDown) 

• nTimes is the number of pages the insertion point will move. If nTi mes is 
omitted, the default is 1. 

• bShi ftlsDown is a Boolean indicating whether or not content is being selected. 
If bShi ftlsDown is true, the content is selected. 

Returns 

Nothing. 

dom,source u getCurrentUnes() 

Availability 

Dreamweaver 4.0 

Description 

Returns the line numbers for the specified offset locations from the beginning of 
the document. 

Arguments 

startOffset, endOffset 

• sta rtOff 'set is an integer representing the beginning line of text. 

• endOffs e t is an integer representing the ending line of text. 
Returns 

An array of two numbers representing the beginning and ending lines of the text 
between (and including) startOffset and endOffset. If sta rtOffset and 
endOffset are not valid, returns -1. 
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dom.source.getSdectsonQ 

Description 

Gets the selection in the current document, expressed as character offsets into the 
documents Code view. 

Arguments 

None. 

Returns 

A pair of integers representing offsets from the beginning of the source document. 
The first integer is the beginning of the selection, and the second is the end of the 
selection. If the two numbers are equal, the selection is an IP. If there is no 
selection in the source, both numbers are -1. 

dom.sQurce.getTextQ 

Availability 

Dreamweaver 4.0 

Description 

Returns the text string in the source between the designated offsets. 

Arguments 

start, end 

• s t a r t is an integer representing the offset from the beginning of the 
document. 

• end is an integer representing the end of the document. 
Returns 

A string representing the text in the HTML source code between the offsets 

start and end. 

dom a sourceJndentTextV§ew{) 

Availability 

Dreamweaver 4.0 

Description 

Moves selected source view text one tab stop to the right. 

Arguments 

None 

Returns 

Nothing. 
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dom.sourceJnsertQ 

Description 

Inserts the specified string into the HTML source code at the specified offset from 
the beginning of the source file. If the offset is not greater than, or equal to, zero, 
the insertion fails and the function returns false. 

Arguments 

offset, string 

• o ffs e t is the offset from the beginning of the file where the string should 
be inserted. 

• string is the string to insert. 
Returns 

true if successful, fal se if not. 

doiTLSGiirce. next WordQ 

Availability 

Dreamweaver 4.0 

Description 

Moves the insertion point to the beginning of the next word (or words, if 
specified) in the Source view. If content is already selected, this function extends 
the selection to the right. 

Arguments 

{nTimes}, (bShi ftlsDown} 

• n Times is the number of words the insertion point will move. If nTi mes is 
omitted, the default is 1. 

• bShi ftlsDown is a Boolean indicating whether or not content is being selected. 
If bShi ftlsDown is true, the content is selected. 

Returns 

Nothing. 
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dom.source.outdentTextVsewQ 

Availability 

Dreamweaver 4.0 

Description 

Moves selected source view text one tab stop to the left. 

Arguments 

None 

Returns 

Nothing. 

dom.source.pageDownQ 

Availability 

Dreamweaver 4.0 

Description 

Moves the insertion point down the source view document, page by page. If 
content is already selected, this function extends the selection page by page. 

Arguments 

{nTimes}, {bShi ftlsDown} 

• nTimes is the number of pages the insertion point will move. If nTi mes is 
omitted, the default is 1 . 

• bSh i ftlsDown is a Boolean indicating whether or not content is being selected. 
If bShi ftlsDown is true, the content is selected. 

Returns 

Nothing. 
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dom.source.pageUpQ 

Availability 

Dreamweaver 4.0 

Description 

Moves the insertion point up the source view document, page by page. If content 
is already selected, this function extends the selection page by page. 

Arguments 

{nTimes}, {bShi ftlsDown} 

• nTimes is the number of pages the insertion point will move. If nTi mes is 
omitted, the default is 1 . 

• bSh i ftlsDown is a Boolean indicating whether or not content is being selected. 
If bShi ftlsDown is true, the content is selected. 

Returns 

Nothing. 

dom.source.previousWord() 

Availability 

Dreamweaver 4.0 

Description 

Moves the insertion point to the beginning of the previous word (or words if 
specified) in the source view. If content is already selected, this function extends 
the selection to the left. 

Arguments 

{nTimes}, (bShi ftlsDown} 

• nTimes is the number of words the insertion point will move. If nTi mes is 
omitted, the default is 1 . 

• bShi ftlsDown is a Boolean indicating whether or not content is being selected. 
If bShi ftlsDown is true, the content is selected. 

Returns 

Nothing. 
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dom.source.replaceRangeQ 

Availability 

Dreamweaver 4.0 

Description 

Replaces the range of source text between startOffset and endOff set with 
string. If startOffset is greater than endOffset or if either offset is not a 
positive integer, does nothing and returns fal se. If endOffset is greater than the 
number of characters in the file, replaces the range between startOffset and the 
end of the file. If both startOffset and endOffset are greater than the number 
of characters in the file, inserts the text at the end of the file. 

Arguments 

startOffset, endOffset, string 

• startOffset is the offset indicating the beginning of the block to replace. 

• endOffset is the offset indicating the end of the block to replace. 

• string is the string to insert. 
Returns 

true if successful, fal se if not. 

dom.soiirce n scronEndFiie{) 

Availability 

Dreamweaver 4.0 

Description 

Scrolls the Source view to the bottom of the document file without moving the 
insertion point. 

Arguments 

None. 

Returns 

Nothing. 
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dom.source.scrollLmeDownQ 

Availability 

Dreamweaver 4.0 

Description 

Scrolls the Source view down line by line without moving the insertion point. 

Arguments 

nTimes 

nTimes is the number of lines to scroll. If nTi mes is omitted, the default is 1. 

Returns 

Nothing. 

dom.source.scrollLmeUpQ 

Availability 

Dreamweaver 4.0 

Description 

Scrolls the Source view up line by line without moving the insertion point. 

Arguments 

nTimes 

nTimes is the number of lines to scroll. If nTi mes is omitted, the default is 1. 

Returns 

Nothing. 

dom.sQurce.scrollFageDownQ 

Availability 

Dreamweaver 4.0 

Description 

Scrolls the Source view down page by page without moving the insertion point. 

Arguments 

nTimes 

nTimes is the number of pages to scroll. If nTi mes is omitted, the default is 1. 

Returns 

Nothing. 
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dom.source.scrollPageUpQ 



Availability 

Dreamweaver 4.0 

Description 

Scrolls the Source view up page by page without moving the insertion point. 

Arguments 

nTimes 

nTimes is the number of pages to scroll. If nTi mes is omitted, the default is 1. 

Returns 

Nothing. 

dom.source.scrollTopFileO 

Availability 

Dreamweaver 4.0 

Description 

Scrolls the Source view to the top of the document file without moving the 
insertion point. 

Arguments 

None. 

Returns 

Nothing. 

dom,source.selectParentTag(} 

Availability 

Dreamweaver 4.0 

Description 

Source view extension that enables tag balancing. You can call 
dom. source. selectParentTagO to extend a currently highlighted selection or 
insertion point from the surrounding open tag to the closing tag. Subsequent calls 
extend the selection to additional surrounding tags until there are no more 
enclosing tags. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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dom.source.setCurrentUneQ 

Availability 

Dreamweaver 4.0 

Description 

Puts the insertion point at the beginning of the specified line. If / ineNumber is 
not a positive integer, does nothing and returns f a 1 se. Puts the insertion point at 
the beginning of the last line if 7 ineNumber is larger than the number of lines in 
the source. 

Arguments 

/ ineNumber 

1 ineNumber is the line at the beginning of which the insertion point is placed. 
Returns 

true if successful, fal se if not. 

dom.soLirce.startOfDocismentO 

Availability 

Dreamweaver 4.0 

Description 

Places the insertion point at the beginning of the source view document. If 
content is already selected, this function extends the selection to the beginning of 
the document. 

Arguments 

bShi ftlsDown 

A Boolean indicating whether or not content is being selected. If bShi ft I sDowin is 
true, the content is selected. 

Returns 

Nothing. 
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dom.source.startQfUneQ 

Availability 

Dreamweaver 4.0 

Description 

Places the insertion point at the beginning of the current line. If content is already 
selected, this function extends the selection to the beginning of the current line. 

Arguments 

bShi ftlsDown 

A Boolean indicating whether or not content is being selected. If bShi ft I sDowin is 
true, the content is selected. 

Returns 

Nothing. 

dom.source n topPage() 

Availability 

Dreamweaver 4.0 

Description 

Moves the insertion point to the top of the current page or to the top of the 
previous page (if the insertion point is already at the top of a page). If content is 
already selected, this function extends the selection page by page. 

Arguments 

(nTimesj, (bShiftlsDown} 

• nTimes is the number of pages the insertion point will move. If nTi mes is 
omitted, the default is 1 . 

• bShi ftlsDown is a Boolean indicating whether or not content is being selected. 
If bShi ftlsDown is true, the content is selected. 

Returns 

Nothing. 
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doiTLSOurce.wrapSelectaonQ 

Availability 

Dreamweaver 4.0 

Description 

Inserts the text of startTag before the current selection and the text of endTag 
after the current selection. The function then selects the entire range that has just 
been inserted. If the current selection was an insertion point, then the function 
places the insertion point between the startTag and endTag. startTag and 
endTag don't have to be tags; they can be any arbitrary text. 

Arguments 

startTag, endTag 

• sta rtTag is the text to insert at the beginning of the selection. 

• endTag Is the text to insert at the end of the selection. 

Returns 

Nothing. 

dom,synchronazeDocurnent() 

Availability 

Dreamweaver 4.0 

Description 

Synchronizes the Design and Source views. 

Arguments 

None. 

Returns 

Nothing. 
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String manipulation functions 

String manipulation functions help you get information about a string, as well as 
convert a string from Latin 1 encoding to platform-native encoding and back. 



drearnweaver-doURLEncodlngO 

Availability 

Dreamweaver 1.0 

Description 

This function takes a string and returns a URL-encoded string by replacing all 
spaces and special characters with specified entities. 

Arguments 

stringToConvert 

Returns 

A URL-encoded string. 

Enabler 

None. 

Example 

If the URL.value is " My URL-encoded string": 
var URL = dw . doURLEncodi ng( theURL . val ue) ; 
returns "My%20URL-encoded%20st.ri ng" 
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dreamweaver.getTokensQ 

Availability 

Dreamweaver 1.0 

Description 

Accepts a string and splits it into tokens. 
Arguments 

searchStri ng, separatorCharacters 

• sea rchStr i ng is the string to be separated into tokens. 

• separatorCharacters is the character or characters that signifies the 
end of a token. Separator characters in quoted strings are ignored. If 
separatorCharacters contains a space, all white-space characters (for 
example, tabs) are treated as separator characters as if you had explicitly 
specified them. Two or more consecutive white space characters are treated 
as a single separator. 

Returns 

An array of token strings. 

Enabler 

None. 

Example 

dreamweaver . getTokens ( ' foo( "my argl", 34)', '(),') returns the tokens: 

• foo 

• "my arg 1" 

• 34 
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dreamweaverJatinUoMativeO 

Availability 

Dreamweaver 2.0 

Description 

Converts a string in Latin 1 encoding to the native encoding on the users 
machine. This function is intended for displaying the user interface of an 
extension file in another language. 

Note: This function has no effect in Windows because Windows encodings are already 
based on Latin! 

Arguments 

stri ngToConvert 

stringToConvert is the (already translated) string to be converted from Latin 1 
encoding to native encoding. 

Returns 

The converted string. 

Enabler 

None. 



dreamweaver.natsveToLatinlQ 

Availability 

Dreamweaver 2.0 

Description 

Converts a string in native encoding to Latin 1 encoding. 

Note: This function has no effect in Windows because Windows encodings are already 
based on Latin! 

Arguments 

stringToConvert 

stri ngToConvert is the string to be converted from native encoding to 
Latin 1 encoding. 

Returns 

The converted string. 

Enabler 

None. 
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The dreamweaver . scanSourceStri ng( ) function is a utility function that 
analyzes a string and deciphers where the HTML tags, attributes, and directives 
are located. Here is a scenario for using the dreamweaver . scanSourceStri ng( ) 
function: 

1 You create an implementation for one or more of the seven callback functions. 

2 Youwrite a script that calls the dreamweaver . scanSourceStri ng( ) function. 

3 The dreamweaver . scanSourceStri ng( ) function is passed a string 
containing HTML and pointers to the callback functions that you have 
written. For example, suppose the string of HTML is "<font 
size=2>hel lo</font>". 

4 Dreamweaver analyzes the string and determines that the string contains a font 
tag. Dreamweaver calls the callback functions in the following sequence: 

• the openTagBegi n( ) function 

• the a 1 1 r i b u t e ( ) function (for the size attribute) 

• the openTagEnd( ) function 

• the text ( ) function (for the "hello" string) 

• the cl oseTagBegi n( ) and cl oseTagEnd( ) functions 
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dreamweaver.scanSourceString callback functions 

As mentioned, there are seven callback functions that Dreamweaver calls: 

1 Dreamweaver calls openTagBeginO for each opening tag (for example, 

< font), as opposed to </font>) and each empty tag (for example, <img> or 
<hr>).The openTagBeginO function accepts two arguments: the name of the 
tag (for example, " f on t " or " i mg ") and the document offset, which is the 
number of bytes in the document before the beginning of the tag. The function 
returns true if scanning should continue, or fal se if it should stop. 

2 After openTagBeginO executes, Dreamweaver calls a 1 1 r i b u t e ( ) for each 
HTML attribute. The attributeO function accepts two arguments: a string 
containing the attribute name (for example, "color" or " s re ") and a string 
containing the attribute value (for example, "#000000" or " f oo . gi f "). The 
attri bute( ) function returns a Boolean indicating whether or not scanning 
should continue. 

3 After all of the attributes in the tag have been scanned, Dreamweaver calls 
openTagEnd( ). The openTagEncK ) function accepts one argument: the 
document offset, which is the number of bytes in the document before the end 
of the opening tag. It returns a Boolean indicating whether or not scanning 
should continue. 

4 Dreamweaver calls cl oseTagBegi n ( ) for each closing tag (for example, </ 
font)). The function accepts two arguments: the name of the tag to close (for 
example, " f ont ") and the document offset, which is the number of bytes in the 
document before the beginning of the close tag. The function returns a 
Boolean indicating whether or not scanning should continue. 

5 After cl oseTagBegi n( ) returns, Dreamweaver calls the cl oseTag End ( ) 
function. The cl oseTag End ( ) function accepts one argument: the 
document offset, which is the number of bytes in the document before the end 
of the closing tag. It returns a Boolean indicating whether or not scanning 
should continue. 

8 Dreamweaver calls the d i rec t i v e ( ) function for each HTML comment, ASP 
script, JSP script, or PHP script. The di recti ve ( ) function accepts two 
arguments: a string containing the directive and the document offset, which 
is the number of bytes in the document before the end of the closing tag. 
The function returns a Boolean indicating whether or not scanning 
should continue. 

7 Dreamweaver calls the text ( ) function for each span of text in the document, 
that is, everything that is not a tag or a directive. Text spans include text that is 
not visible to the user, such as the text inside a <ti tl e> or <opti on> tag. The 
text ( ) function accepts two arguments: a string containing the text and the 
document offset, which is the number of bytes in the document before the end 
of the closing tag. The text ( ) function returns a Boolean indicating whether 
or not scanning should continue. 
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dreamweaver.scanSourceStringQ 



Availability 

Dreamweaver UltraDev 1 .0 
Description 

Scans a string of HTML and finds the tags, attributes, directives, and text. For 
each tag, attribute, directive, and text span found, scanSourceStringO invokes 
a callback function supplied by the caller. Dreamweaver supports the following 
callback functions: openTagBegi n ( ), openTagEncK ), cl oseTagBegi n( ), 
cl oseTagEncK ), di recti ve( ), attri bute( ), and text( ). 

Arguments 

HTMLstr, parserCa 1 1 backObj 

• HTMLstr is a string containing HTML code. 

• parserCal 1 backObj is a JavaScript object that has one or more of the 
following methods: openTagBegi n ( ), openTagEnd ( ), cl oseTagBegi n ( ), 
cl oseTagEncK ), di recti ve( ), attri bute( ), and text( ). For best 
performance, parserCa 1 1 backObj should be a shared library defined using the 
C-Level Extensibility interface. Performance is also improved if 
parserCal 1 backObj defines only the callback functions that it needs. 

Returns 

A Boolean value indicating whether or not the operation completed successfully. 

Table editing functions 

Table functions add and remove table rows and columns, change column widths 
and row heights, convert measurements from pixels to percents and back, and 
perform other standard table editing tasks. 

dom.convertWidthsToPercent() 

Availability 

Dreamweaver 3.0 

Description 

Converts all W I DTH attributes in the current table from pixels to percentages. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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domxonvertWidthsToFsxelsQ 

Availability 

Dreamweaver 4.0 

Description 

Converts all W I DTH attributes in the current table from percentages to pixels. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

do*TLdecreaseCo!span() 

Availability 

D reamweaver 3 . 0 

Description 

Decreases the column span by 1. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dom.canDecreaseCol span( ) 

dom.decreaseRowspanO 

Availability 

Dreamweaver 3.0 

Description 

Decreases the row span by 1. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dotn.canDecreaseRowspan( ) 



394 Chapter 20 



dom.deletelableColumnQ 

Availability 

Dreamweaver 3.0 

Description 

Removes the selected table column or columns. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dom.canDel eteTabl eCol umn( ) 

dom,deSeteTabIeRow{) 

Availability 

Dreamweaver 3.0 

Description 

Removes the selected table row or rows. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dotn . can Del eteTabl eRow( ) 
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dom.doDeferredTableUpdate{5 

Availability 

Dreamweaver 3.0 

Description 

If the Faster Table Editing option is selected in the General preferences, forces the 
table layout to reflect recent changes without moving the selection outside the 
table. This function has no effect if the Faster Table Editing option is not selected. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 



dom.getTableExtentQ 

Availability 

Dreamweaver 3.0 

Description 

Gets the number of columns and rows in the selected table. 

Arguments 

None. 

Returns 

An array containing two whole numbers. The first array item is the number of 
columns, and the second array item is the number of rows. If no table was 
selected, nothing is returned. 

Enabler 

None. 
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dorrUncreaseGoSspanQ 

Availability 

Dreamweaver 3.0 

Description 

Increases the column span by 1. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dom. canine reaseCols pa n() 

domJncreaseRowspan() 

Availability 

Dreamweaver 3.0 

Description 

Increases the row span by 1. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dom.canIncreaseRowspan( ) 
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domJnsertIabSeColumns() 

Availability 

Dreamweaver 3.0 

Description 

Inserts the specified number of table columns into the current table. 
Arguments 

numberOfCol s, bBeforeSelection 

• numberOfCol s is the number of columns to insert. 

• bBeforeSe lection is a Boolean value indicating whether the columns should 
be inserted before the column that contains the selection. 

Returns 

Nothing. 

Enabler 

dom.canlnsertTabl eCol umns( ) 

domJnsertTabIeRows{) 

Availability 

D ream weaver 3 . 0 

Description 

Inserts the specified number of table rows into the current table. 
Arguments 

numberOfRows, bBeforeSelection 

• numberOfRows is the number of rows to insert. 

• bBeforeSe 1 ecti on is a Boolean value indicating whether the rows should be 
inserted above the row that contains the selection. 

Returns 

Nothing. 

Enabler 

dom.canlnsertTabl eRows( ) 
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dom.rrsergeTableCeiSsQ 

Availability 

Dreamweaver 3.0 

Description 

Merges the selected table cells. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dom . canMergeTabl eCel 1 s( ) 

dom,removeAyiableHesghts() 

Availability 

Dreamweaver 3.0 

Description 

Removes all HEIGHT attributes from the selected table. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

ciom.removeAyTableWidthsO 

Availability 

Dreamweaver 3.0 

Description 

Removes all W I DTH attributes from the selected table. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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dom.setTabieCelITag() 

Availability 

Dreamweaver 3.0 

Description 

Specifies the tag for the selected cell. 

Arguments 

tdOrTh 

tdOrTh must be either "td" or "th". 

Returns 

Nothing. 

Enabler 

None. 

dom,setTableColurnns() 

Availability 

Dreamweaver 3.0 

Description 

Sets the number of columns in the selected table. 

Arguments 

numberOfCol s 

Returns 

Nothing. 

Enabler 

None. 
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dom.setTabieRowsQ 

Availability 

Dreamweaver 3.0 

Description 

Sets the number of rows in the selected table. 

Arguments 

numberOfRows 

Returns 

Nothing. 

Enabler 

None. 

dom.showfnsertlableRowsOrCoIumnsDBalogO 

Availability 

D ream weaver 3 . 0 

Description 

Opens the Insert Rows or Columns dialog box. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dom.canlnsertTabl eCol umns( ) or dom. canlnsertTabl eRows( ) 
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dom.spHtTableCeliQ 

Availability 

Dreamweaver 3.0 

Description 

Splits the current table cell into the specified number of rows or columns. If one 
or both of the arguments is omitted, the Split Cells dialog box appears. 

Arguments 

{col sOrRows}, (numberToSpl it Into} 

• co 1 sOrRows, if supplied, must be either " col umns " or "rows". 

• numberToSp 7 itlnto, if supplied, is the number of rows or columns to split the 
cell into. 

Returns 

Nothing. 

Enabler 

dom.canSpl itTabl eCel 1 ( ) 



Timeline functions 

Timeline functions act on timelines. They add, remove, and change objects in a 
timeline; add behaviors, frames, and keyframes to a timeline; specify whether the 
timeline should play and loop automatically; and more. All of the functions in this 
section are methods of the dreamweaver . ti mel inelnspector object because 
they affect the contents of the Timelines panel. 



drearfYweaver-tsmeHne^nspector.addBehaviorO 

Availability 

Dreamweaver 3.0 

Description 

Opens the Behaviors panel and automatically supplies the correct onFrameN event 
(where N is the frame marked by the playback head) when the user chooses an 
action and clicks OK. 



Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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dreamweaver.timeHnelnspector,addFrame() 

Availability 

Dreamweaver 3.0 

Description 

Adds a frame to the current timeline at the frame that contains the playback head. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamweaver . timel i ne Inspector . canAddFrame( ) 

dreamweaver n timeHnefnspector 0 addKeyframe() 

Availability 

Dreamweaver 3.0 

Description 

Adds a keyframe to the selected animation bar at the frame that contains the 
playback head. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamweaver . timel i ne Inspector . canAddKeyFrame( ) 

dreamweaver D tsmeHnelnspector B addObject{) 

Availability 

Dreamweaver 3.0 

Description 

Adds the currently selected object to the timeline. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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dreamweaver.timeHnelnspector.addlimeHneO 

Availability 

Dreamweaver 3.0 

Description 

Adds a new timeline to the current document. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

dreamweaver.tfmeHnelnspectorxhangeObject{) 

Availability 

D ream weaver 3 . 0 

Description 

Opens the Change Object dialog box. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamweaver . timel i ne Inspector . canChangeObject ( ) 

dreamweaver n timeHne^nspector 0 getAutopiay() 

Availability 

Dreamweaver 3.0 

Description 

Gets the state of the Autoplay option for the current timeline. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the Autoplay option is selected. 

Enabler 

None. 
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dreamweaver.timeHnelnspector,getCurrentFrame{) 

Availability 

Dreamweaver 3.0 

Description 

Gets the current frame of the current timeline. 

Arguments 

None. 

Returns 

A frame number. 

Enabler 

None. 

dreamweaver.timeHnelnspector,getLoop{) 

Availability 

D ream weaver 3 . 0 

Description 

Gets the state of the Loop option for the current timeline. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the Loop option is selected. 

Enabler 

None. 

dreamweaver.tfmeHnelnspector,recordPathOfLayer() 

Availability 

Dreamweaver 3-0 

Description 

Records the path of a layer as the user drags it. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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dreamweaver.t[meHnelnspector,rernoveBehavior{) 

Availability 

Dreamweaver 3.0 

Description 

Removes the selected behavior from the timeline. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamweaver . timel i ne I inspector . canRemoveBehavi or ( ) 

dreamweaver n timeHnefnspector 0 removeFrame() 

Availability 

Dreamweaver 3.0 

Description 

Removes the selected frame from the timeline. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamweaver . timel i ne I inspector . can Remove Frame ( ) 

dreamweaver«tsmeHne^nspector,rernoveKeyframe() 

Availability 

D ream weaver 3 . 0 

Description 

Removes the selected keyframe from an animation bar. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamweaver . timel i ne Inspector . can Remove Key Frame ( ) 
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dreamweaver.timeHnelnspector,rernoveObject() 

Availability 

Dreamweaver 3.0 

Description 

Removes the currently selected object from the timeline. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dreamweaver . timel i ne Inspector . canRemoveObject ( ) 

dreamweaver n timeHnefnspector 0 removeTimeline() 

Availability 

Dreamweaver 3.0 

Description 

Removes the current timeline from the document. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

dreamweaver n timeHne^nspector 0 renameTimelsne() 

Availability 

Dreamweaver 3.0 

Description 

Opens the Rename Timeline dialog box for the current timeline. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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dreamweaver.timeHnelnspector.setAutoplayO 

Availability 

Dreamweaver 3.0 

Description 

Sets the Autoplay option for the current timeline. 

Arguments 

bAutopl ay 

bAutopl ay is a Boolean value indicating whether to turn on the Autoplay option. 

Returns 

Nothing. 

Enabler 

None. 

dreamweaver.tsmeHne!nspector,setCurren!Frame() 

Availability 

Dreamweaver 3.0 

Description 

Moves the playback head to the specified frame. 

Arguments 

frameNumber 

Returns 

Nothing. 

Enabler 

None. 
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dreamweaver.timeHnelnspector.setLoopO 

Availability 

Dreamweaver 3.0 

Description 

Sets the Loop option for the current timeline. 

Arguments 

bLoop 

b Loop is a Boolean value indicating whether to turn on the Loop option. 

Returns 

Nothing. 

Enabler 

None. 

Toggle functions 

Toggle functions get and set various options either on or off. 

dom.getEditNoFramesContent() 

Availability 

Dreamweaver 3.0 

Description 

Gets the current state of the Modify > Frameset > Edit NoFrames Content option. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the NOFRAMES content is the active view 
(true) or not (fal se). 

Enabler 

None. 
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dom.getHideAyVssiialAidsQ 

Availability 

Dreamweaver 4.0 

Description 

Determines whether or not visual aids are set as hidden. 

Arguments 

None. 

Returns 

A Boolean value, true if "Hide All Visual Aids" is set, fal se otherwise. 

Enabler 

None. 

dom.getPreventLayerOverlaps() 

Availability 

D ream weaver 3 . 0 

Description 

Gets the current state of the Prevent Layer Overlaps option. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the option is on (true) or off (fal se). 

Enabler 

None. 

dom«getShowAutofndent() 

Description 

Determines whether or not auto indenting is on in the Code view of the 
Document window. 

Arguments 

None. 

Returns 

Returns true if auto indenting is on. 
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dom.getShowFrame8orders(5 

Availability 

Dreamweaver 3.0 

Description 

Gets the current state of the View > Frame Borders option. 

Arguments 

None. 

Returns 

A Boolean value indicating whether frame borders are visible (true) or 
not (fal se). 

Enabler 

None. 

dom.getShowGridQ 

Availability 

Dreamweaver 3.0 

Description 

Gets the current state of the View > Grid > Show option. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the grid is visible (true) or not (fa 1 se). 

Enabler 

None. 
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dom.getShowHeadView() 

Availability 

Dreamweaver 3.0 

Description 

Gets the current state of the View > Head Content option. 

Arguments 

None. 

Returns 

A Boolean value indicating whether head content is visible (true) or not (fa 1 se). 

Enabler 

None. 

dom.getShowHighHghtfnvalidHTMLQ 

Availability 

Dreamweaver 4.0 

Description 

Determines whether or not invalid HTML is currently highlighted in the Code 
view of the Document window. 

Arguments 

None. 

Returns 

Returns true if invalid HTML is being highlighted. 

dom,getShowImageMaps() 

Availability 

Dreamweaver 3.0 

Description 

Gets the current state of the View > Image Maps option. 

Arguments 

None. 

Returns 

A Boolean value indicating whether image maps are visible (true) or not (false). 

Enabler 

None. 
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dom.getShowInvisibSeEIementsO 

Availability 

Dreamweaver 3.0 

Description 

Gets the current state of the View > Invisible Elements option. 

Arguments 

None. 

Returns 

A Boolean value indicating whether invisible element markers are visible (true) or 
not (fal se). 

Enabler 

None. 

dom,getShowLayerBorders{) 

Availability 

Dreamweaver 3.0 

Description 

Gets the current state of the View > Layer Borders option. 

Arguments 

None. 

Returns 

A Boolean value indicating whether layer borders are visible (true) or 
not (fal se). 

Enabler 

None. 

dom.getShowUneNumhersQ 

Availability 

Dreamweaver 4.0 

Description 

Determines whether line numbers are displayed in the Code view. 

Arguments 

None. 

Returns 

Returns a Boolean value indicating whether line numbers are shown (true) or 
not (fal se). 
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dom.getShGwRiilersQ 

Availability 

Dreamweaver 3.0 

Description 

Gets the current state of the View > Rulers > Show option. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the rulers are visible (true) or not (fa 1 se). 

Enabler 

None. 

dom.getShowSyntaxCo!onng() 

Availability 

Dreamweaver 4.0 

Description 

Determines whether or not syntax coloring is on in the Code view of the 
Document window. 

Arguments 

None. 

Returns 

Returns true if syntax coloring is on. 

dom,getShowTableBorders() 

Availability 

Dreamweaver 3.0 

Description 

Gets the current state of the View > Table Borders option. 

Arguments 

None. 

Returns 

A Boolean value indicating whether table borders are visible (true) or 
not (fal se). 

Enabler 

None. 
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dom.getShowTooibar() 

Availability 

Dreamweaver 4.0 

Description 

Determines whether or not the toolbar is being shown. 

Arguments 

None. 

Returns 

Returns true if the toolbar is displayed; fa 1 se if the toolbar is not displayed. 

dom.getShowTracsngfmage{) 

Availability 

D ream weaver 3 . 0 

Description 

Gets the current state of the View > Tracing Image > Show option. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the option is on (true) or off (fa 1 se). 

Enabler 

None. 

dom.getShowWordWrap{) 

Availability 

Dreamweaver 4.0 

Description 

Determines whether or not word wrap is on in the Code view ofthe 
Document window. 

Arguments 

None. 

Returns 

Returns true if word wrap is on. 
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dom.getSnapTo6Hd() 

Availability 

Dreamweaver 3.0 

Description 

Gets the current state of the View > Grid > Snap To option. 

Arguments 

None. 

Returns 

A Boolean value indicating whether grid snapping is on (true) or off (fa 1 se). 

Enabler 

None. 

dom.setEditNoFramesContent() 

Availability 

D ream weaver 3 . 0 

Description 

Turns the Modify > Frameset > Edit NoFrames Content option on (true) or 
off (false). 

Arguments 

bEdi tNoFrames 

Returns 

Nothing. 

Enabler 

dom.canEdi tNoFramesContent( ) 
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dom.setHideASMsua!Aids() 

Availability 

Dreamweaver 4.0 

Description 

Turns off the display of all borders, image maps, and invisible elements, regardless 
of their individual settings in the View menu. 

Arguments 

bSet 

bSet is a Boolean value; when set to fal se, the previous settings are restored. 

Returns 

Nothing. 

Enabler 

None. 

dom,setPreventLayerOverlaps() 

Availability 

Dreamweaver 3.0 

Description 

Turns the Prevent Layer Overlaps option on (true) or off (fal se). 
Arguments 

b Prevent Lay erOverl a ps 

Returns 

Nothing. 

Enabler 

None. 
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dom.setShowFranieBordersO 

Availability 

Dreamweaver 3.0 

Description 

Turns the View > Frame Borders option on (true) or off (fa 1 se). 

Arguments 

bShowFrameBorders 

Returns 

Nothing. 

Enabler 

None. 

dom.setShowGridQ 

Availability 

D ream weaver 3 . 0 

Description 

Turns the View > Grid > Show option on (true) or off (fal se). 

Arguments 

hShowGrid 

Returns 

Nothing. 

Enabler 

None. 

dom.setShowHeadViewQ 

Availability 

Dreamweaver 3-0 

Description 

Turns the View > Head Content option on (true) or off (fa 1 se). 

Arguments 

bShowHead 

Returns 

Nothing. 

Enabler 

None. 
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dom.setShowHighHghtfnvaHdHTML() 

Availability 

Dreamweaver 4.0 

Description 

Turns highlighting of invalid HTML on or off in the Code view of the 
Document window. 

Arguments 

bShow 

bShow is a Boolean value indicating whether the highlighting of invalid HTML 
should be visible (true) or not (fal se). 

Returns 

Nothing. 

dom.setShowImageMaps() 

Availability 

Dreamweaver 3.0 

Description 

Turns the View > Image Maps option on (true) or off (fal se). 

Arguments 

bShowImageMaps 

Returns 

Nothing. 

Enabler 

None. 

dom a setShow!nviS!bSeEIements{) 

Availability 

Dreamweaver 3.0 

Description 

Turns the View > Invisible Elements option on (true) or off (fal se). 
Arguments 

bVi ewl nvi si bl eEl ements 

Returns 

Nothing. 

Enabler 

None. 
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dom.setShowLayerBordersQ 

Availability 

Dreamweaver 3.0 

Description 

Turns the View > Layer Borders option on (true) or off(f al se). 

Arguments 

bShowLayerBorders 

Returns 

Nothing. 

Enabler 

None. 

dom.setShowLsneNurnbers() 

Availability 

Dreamweaver 4.0 

Description 

Shows or hides the line numbers in the Code view of the Document window. 

Arguments 

bShow 

bShow is a Boolean value indicating whether the line numbers should be visible 
(true) or not (fal se). 

Returns 

Nothing. 

dofY^setShowRulersQ 

Availability 

Dreamweaver 3.0 

Description 

Turns the View >Rulers > Show option on (true) or off (fa 1 se). 

Arguments 

bShowRul ers 

Returns 

Nothing. 

Enabler 

None. 
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dom.setShowSyntaxColoring{) 

Availability 

Dreamweaver 4.0 

Description 

Turns syntax coloring on or off in the Code view of the Document window. 

Arguments 

bShow 

bShow is a Boolean value indicating whether the syntax coloring should be visible 
(true) or not (fal se). 

Returns 

Nothing. 

dofY^setShowTableBordersQ 

Availability 

Dreamweaver 3.0 

Description 

Turns the View > Table Borders option on (true) or off (fa 1 se). 

Arguments 

bShowTabl eBorders 

Returns 

Nothing. 

Enabler 

None. 

dom,setShowToolbar() 

Availability 

Dreamweaver 4.0 

Description 

Shows or hides the Toolbar. 

Arguments 

bShow 

bShow is a Boolean value indicating whether the toolbar should be visible (true) 
or not (fal se). 

Returns 

Nothing. 
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dom.setShowTracsng!mage() 

Availability 

Dreamweaver 3.0 

Description 

Turns the View > Tracing Image > Show option on (true) or off (fal se). 

Arguments 

bShowTraci nglmage 

Returns 

Nothing. 

Enabler 

None. 

doiTLsetShowWordWrapQ 

Availability 

Dreamweaver 4.0 

Description 

Turns word wrap off or on in the Code view of the Document window. 

Arguments 

bShow 

bShow is a Boolean value indicating whether the line numbers should be visible 
(true) or not (fal se). 

Returns 

Nothing. 

dofY^setSnapToGrad() 

Availability 

Dreamweaver 3.0 

Description 

Turns the View > Grid > Snap To option on (true) or off (fa 1 se). 

Arguments 

bSnapToGrid 

Returns 

Nothing. 

Enabler 

None. 
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dreamweaver.getHkleAHFIoatersQ 

Availability 

Dreamweaver 3.0 

Description 

Gets the current state of the Hide Floating Panels option. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the Hide Floating Panels option (true) or the 
Show Floating Panels option (fal se) is available. 

Enabler 

None. 

dreamweaver.getShowStatusBarQ 

Availability 

Dreamweaver 3.0 

Description 

Gets the current state of the View > Status Bar option. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the status bar is visible (true) or not (fa 1 se). 

Enabler 

None. 

drearnweaver u htrrslSnspector.getShowAutofndent{) 

Availability 

Dreamweaver 4.0 

Description 

Determines whether or not auto indenting is on in the Code view of the 
Code inspector. 

Arguments 

None. 

Returns 

Returns true if auto indenting is on. 
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dreamweaver.htmSfnspector a getShowHBghHghthwaHdHTML{) 

Description 

Determines whether or not invalid HTML is currently highlighted in the Code 
view of the Code inspector. 

Arguments 

None. 

Returns 

Returns true if invalid HTML is currently highlighted. 

dreamweaver.htrnSfnspector n getShowLineNumbers() 

Availability 

Dreamweaver 4.0 

Description 

Determines whether or not line numbers are being shown in the Code view of the 
Code inspector. 

Arguments 

None. 

Returns 

Returns true if line numbers are shown. 

dreamweaver.htrn^nspector»getShowSyntaxCobrsng(5 

Availability 

Dreamweaver 4.0 

Description 

Determines whether or not syntax coloring is on in the Code view of the 
Code inspector. 

Arguments 

None. 

Returns 

Returns true if syntax coloring is on. 
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dreamweaver.htrnSfnspector.getShowWordWrapC) 

Availability 

Dreamweaver 4.0 

Description 

Determines whether or not word wrap is on in the Code view ofthe 
Code inspector. 

Arguments 

None. 

Returns 

Returns true if word wrap is on. 

dreamweaver.htrn^nspector»setShowAuto!ndent() 

Availability 

Dreamweaver 4.0 

Description 

Turns auto indenting on or off in the Code view of the Code inspector. 

Arguments 

bShow 

bShow is a Boolean value indicating whether the auto indenting should be on 
(true) or off (fal se). 

Returns 

Nothing. 

dreamweaverJitm^nspectof\setShowHgghHghtfnvalsdHTML() 

Availability 

Dreamweaver 4.0 

Description 

Turns highlighting of invalid HTML on or off in the Code view of the 
Code inspector. 

Arguments 

bShow 

bShow is a Boolean value indicating whether the highlighting of invalid HTML 
should be visible (true) or not (fal se). 

Returns 

Nothing. 
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dreamweaver.htrnSfnspector a setShowUneNumbers{) 

Availability 

Dreamweaver 4.0 

Description 

Shows or hides the line numbers in the Code view of the Code inspector. 

Arguments 

bShow 

bShow is a Boolean value indicating whether the line numbers should be visible 
(true) or not (fal se). 

Returns 

Nothing. 

dreamweaver u htmlSnspector»setShowSynfaxColormg() 

Availability 

Dreamweaver 4.0 

Description 

Turns syntax coloring on or off in the Code view of the Code inspector. 

Arguments 

bShow 

bShow is a Boolean value indicating whether the syntax coloring should be visible 
(true) or not (fal se). 

Returns 

Nothing. 

dreamweaverJitmlSnspector.setShowWorclWrapO 

Availability 

Dreamweaver 4.0 

Description 

Turns word wrap off or on in the Code view of the Code inspector. 

Arguments 

bShow 

bShow is a Boolean value indicating whether the word wrapping should be on 
(true) or off (fal se). 

Returns 

Nothing. 
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dreamweaver.setHsdeAHFioatersQ 

Availability 

Dreamweaver 3.0 

Description 

Turns on either the Hide Floating Panels option (true) or the Show Floating 
Panels option (fal se). 

Arguments 

bS how Float ingPa lettes 

Returns 

Nothing. 

Enabler 

None. 

drearnweaver H setShowSfatusBar() 

Availability 

Dreamweaver 3.0 

Description 

Turns the View > Status Bar option on (true) or off (fal se). 

Arguments 

bShowStatusBar 

Returns 

Nothing. 

Enabler 

None. 
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site.getShowDependentsQ 

Availability 

Dreamweaver 3.0 

Description 

Gets the current state of the Show Dependent Files option. 

Arguments 

None. 

Returns 

A Boolean value indicating whether dependent files are visible in the site map 
(true) or not (fal se). 

Enabler 

None. 



3itagetShowHiddenFnes() 

Availability 

Dreamweaver 3.0 

Description 

Gets the current state of the Show Files Marked as Hidden option. 

Arguments 

None. 

Returns 

A Boolean value indicating whether hidden files are visible in the site map (true) 
or not (fal se). 

Enabler 

None. 
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site.getShowFageTsttesQ 

Availability 

Dreamweaver 3.0 

Description 

Gets the current state of the Show Page Titles option. 

Arguments 

None. 

Returns 

A Boolean value indicating whether page titles are visible in the site map (true) or 
not (fal se). 

Enabler 

None. 

sitagetShowTooiTlpsQ 

Availability 

Dreamweaver 3.0 

Description 

Gets the current state of the Tool Tips option. 

Arguments 

None. 

Returns 

A Boolean value indicating whether tool tips are visible in the Site window (true) 
or not (fal se). 

Enabler 

None. 
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site.setShowDependentsQ 

Availability 

Dreamweaver 3.0 

Description 

Turns the Show Dependent Files option in the site map on (true) or off (fa 1 se). 
Arguments 

bShowDependentFi les 

Returns 

Nothing. 

Enabler 

None. 

site.setShowH&ddenFslesQ 

Availability 

Dreamweaver 3.0 

Description 

Turns the Show Files Marked as Hidden option in the site map on (true) or 
off (false). 

Arguments 

bShowHi ddenFi les 

Returns 

Nothing. 

Enabler 

None. 

sitasetShowFageTstiesQ 

Availability 

D ream weaver 3 . 0 

Description 

Turns the Show Page Titles option in the site map on (true) or off (fal se). 

Arguments 

bShowPageTitles 

Returns 

Nothing. 

Enabler 

si te . canShowPageTi tl es( ) 
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site.setShowToolTlpsO 

Availability 

Dreamweaver 3.0 

Description 

Turns the Tool Tips option on (true) or off (fa 1 se). 

Arguments 

bShowToolTips 

Returns 

Nothing. 

Enabler 

None. 



Translation functions 

Translation functions deal either directly with translators or with the results of 
translation. These functions get information about or run a translator, edit 
content in a locked region, and specify that the translated source should be used 
when getting and setting selection offsets. 



domsunTmnslaiorQ 

Availability 

Dreamweaver 3.0 

Description 

Runs the specified translator on the document. This function is valid only for the 
active document. 

Arguments 

trans latorName 

t ran si a tor Name is the name of a translator as it appears in the 
Translation preferences. 

Returns 

Nothing. 

Enabler 

None. 
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dreamweaver.editLockedRegbnsQ 

Availability 

Dreamweaver 2.0 

Description 

Depending on the value of the argument, makes locked regions editable or 
noneditable. By default, locked regions are noneditable; if you try to edit a locked 
region before specifically making it editable with this function, Dreamweaver 
beeps and disallows the change. 

Note: Editing locked regions can have unintended consequences for library items 
and templates. It is not recommend that you use this function outside the context of 
data translators. 

Arguments 

bA 1 lowEdits 

bA 1 lowEdi ts is a Boolean value indicating that edits are allowed (true) or 
not allowed (fal se). Dreamweaver automatically restores locked regions to 
their default (noneditable) state when the script that calls this function 
finishes executing. 

Returns 

Nothing. 

Enabler 

None. 



drearnweaver H getTranslatorList(} 

Availability 

D ream weaver 3 . 0 

Description 

Gets a list of the installed translators. 

Arguments 

None. 

Returns 

An array of strings, each representing the name of a translator as it appears in the 
Translation preferences. 

Enabler 

None. 
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dreamweaver.useTranslatedSourceQ 



Availability 

Dreamweaver 2.0 

Description 

Specifies that the values returned bydom.nodeToOffsetsO and 
dom. getSel ecti on( ) and used by dom . of f setsToNode( ) and 
dom.setSelectionO should be offsets into the translated source (the HTML 
contained in the DOM after a translator is run), not the untranslated source. 

Note: This function is relevant only in Property Inspector files. 

Arguments 

bilseTransl atedSource 

The default value of the argument is fal se. Dreamweaver automatically 
uses the untranslated source for subsequent calls to dw.getSelectionO, 
dw. setSel ecti on( ), dw . nodeToOf f sets ( ), and dw . of f setsToNode( ) 
when the script that calls dw.useTranslatedSourceO finishes executing, 
if dw. useTransl atedSource( ) is not explicitly called with an argument of 
fal se before then. 

Returns 

Nothing. 

Enabler 

None. 
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Layout environment functions 

Layout environment functions handle operations related to the settings for 
working on a document. They affect the source, position, and opacity of the 
tracing image; get and set the ruler origin and units; turn the grid on and off 
and change its settings; and play or stop playing plugins. 

dom.getRuIerOrigin() 

Availability 

D ream weaver 3 . 0 

Description 

Gets the origin of the ruler. 

Arguments 

None. 

Returns 

An array of two integers. The first array item is the x coordinate of the origin, and 
the second array item is the y coordinate of the origin. Both values are in pixels. 

Enabler 

None. 

dom.getRuSerUnfeQ 

Availability 

D ream weaver 3 . 0 

Description 

Gets the current ruler units. 

Arguments 

None. 

Returns 

A string containing one of the following values: 

• "in" 

• "cm" 

• "px" 

Enabler 

None. 



434 Chapter 20 



dom.getTrac§ngImageOpacity() 

Availability 

Dreamweaver 3.0 

Description 

Gets the opacity setting for the document's tracing image. 

Arguments 

None. 

Returns 

A value between 0 and 100, or nothing if no opacity is set. 
Enabler 

dom . hasTraci nglmage( ) 
domJoadTracsngfrnageQ 

Availability 

Dreamweaver 3.0 

Description 

Opens the Select Image Source dialog box. If the user selects an image and clicks 
OK, the Page Properties dialog box opens with the Tracing Image field filled in. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

dom.playAyPIugansQ 

Availability 

Dreamweaver 3-0 

Description 

Plays all plugin content in the document. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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dom.playP!ugin() 

Availability 

Dreamweaver 3.0 

Description 

Plays the selected plugin item. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dom.canPl ayPl ugin( ) 
dom.setRuIerOrigmQ 

Availability 

Dreamweaver 3.0 

Description 

Sets the origin of the ruler. 
Arguments 

xCoordi nate, yCoordi nate 

• xCoord i na te is a value, expressed in pixels, on the horizontal axis. 

• y Coord in a te is a value, expressed in pixels, on the vertical axis. 

Returns 

Nothing. 

Enabler 

None. 
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dom.setRiilerUnstsQ 

Availability 

Dreamweaver 3.0 

Description 

Sets the current ruler units. 

Arguments 

uni ts 

units must be " px " , " i n " , or " cm " . 

Returns 

Nothing. 

Enabler 

None. 

dom,setTracmgfmagePos5taon{) 

Availability 

Dreamweaver 3.0 

Description 

Moves the top left corner of the tracing image to the specified coordinates. If the 
arguments are omitted, the Adjust Tracing Image Position dialog box appears. 

Arguments 

x, y 

Returns 

Nothing. 

Enabler 

dotn. hasTraci nglmage( ) 
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dom.setTracsngfmageOpadtyQ 

Availability 

Dreamweaver 3.0 

Description 

Sets the opacity of the tracing image. 

Arguments 

opaci tyPercentage 

opaci tyPercentage must be a number between 0 and 100. 

Returns 

Nothing. 

Enabler 

dom. hasTraci nglmage( ) 
Example 

The following code sets the opacity of the tracing image to 30%: 

dw. get Document DOM ( ) . setTraci ngOpaci ty( ' 30 ' ) ; 

dom.snapTradngfrnageToSeSectionO 

Availability 

Dreamweaver 3.0 

Description 

Aligns the top left corner of the tracing image with the top left corner of the 
current selection. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

dom. hasTraci nglmage( ) 
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dorrLStopAyPIugmsQ 

Availability 

Dreamweaver 3.0 

Description 

Stops all plugin content that is currently playing in the document. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

dom.stopPiuginQ 

Availability 

D ream weaver 3 . 0 

Description 

Stops the selected plugin item. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the selection is currently being played 
with a plugin. 

Enabler 

dotn. canStopPl ugi n( ) 
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dreamweaver.arrangeFSoatangPalettesO 

Availability 

Dreamweaver 3.0 

Description 

Moves the visible floating panels to their default positions. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 



dreamweaver.showGndSettmgsDiatogC) 

Availability 

D reamweaver 3 . 0 

Description 

Opens the Grid Settings dialog box. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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Layout view functions 



Layout view functions handle operations that change the layout elements within a 
document. They affect table, column, and cell settings, including position, 
properties, and appearance. 

dom.addSpacerloColumnQ 

Availability 

Dreamweaver 4.0 

Description 

Creates a one-pixel-high transparent spacer image at the bottom of the given 
column in the currently selected table. This function fails if the current selection 
is not a table or if the operation wasn't successful. 

Arguments 

co 1 Nuifl 

col Hum is the column at the bottom of which the spacer image is created. 

Returns 

Nothing. 

dom,createLayoutCey(5 

Availability 

Dreamweaver 4.0 

Description 

Creates a layout cell in the current document at the specified position and 
dimensions, either within an existing layout table or in the area below the 
existing content on the page. If the cell is being created in an existing layout 
table, it must not overlap or contain any other layout cells or nested layout 
tables. If the rectangle is not inside an existing layout table, Dreamweaver tries 
to create a layout table to house the new cell. This function does not force the 
document into Layout view. This function fails if the cell can't be created. 

Arguments 

/eft, top, width, height 

• 1 eft Is the x position of the left border of the cell. 

• top is the y position of the top border of the cell. 

• width is the width of the cell in pixels. 

• height is the height of the cell in pixels. 

Returns 

Nothing. 
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dom.createLayoutTabSeQ 

Availability 

Dreamweaver 4.0 

Description 

Creates a layout table in the current document at the specified position and 
dimensions, either within an existing table or in the area below the existing 
content on the page. If the table is being created in an existing layout table, it 
cannot overlap other layout cells or nested layout tables, but can contain other 
layout cells or nested layout tables. This function does not force the document 
into Layout view. This function fails if the table can t be created. 

Arguments 

left, top, width, height 

• left is the x position of the left border of the table. 

• top is the y position of the top border of the table. 

• w i d t h is the width of the table in pixels . 

• height Is the height of the table in pixels. 

Returns 

Nothing. 

dom.doesColumnHaveSpacer{) 

Availability 

Dreamweaver 4.0 

Description 

Determines whether or not a column contains a spacer image that Dreamweaver 
generated. This function fails if the current selection is not a table. 

Arguments 

col Hum 

col N urn is the column to check for a spacer image. 
Returns 

Returns true if the specified column in the currently selected table contains a 
spacer image that Dreamweaver generated; returns fal se otherwise. 
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dom.doesGroupHaveSpacersQ 



Availability 

Dreamweaver 4.0 

Description 

Determines whether or not the currently selected table contains a row of spacer 
images that Dreamweaver generated. This function fails if the current selection is 
not a table. 

Arguments 

None. 

Returns 

Returns true if the table contains a row of spacer images; f a 1 se otherwise. 

dom,ge!CHckedHeaderColumn{) 

Availability 

Dreamweaver 4.0 

Description 

If the user has just clicked a menu button in the header of a table in Layout view, 
causing the table header menu to appear, this function returns the index of the 
column the user clicked on. The result is undefined if the table header menu 
isn't visible. 

Arguments 

None. 

Returns 

An integer representing the index of the column. 

dom,getShowLayoutTabSeTabs() 

Description 

Determines whether or not the current document shows tabs for layout tables 
while in Layout view. 

Arguments 

None. 

Returns 

Returns true if the current document displays tabs for layout tables while in 
Layout view, fal se otherwise. 
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dom.getShowLayoutVfew{) 

Description 

Determines the view for the current document, either Layout view or 
Standard view. 

Arguments 

None. 

Returns 

Returns true if the current document is in Layout view, f a 1 se if the document is 
in Standard view. 

dorYtJsColumnAiitostretch{) 

Availability 

Dreamweaver 4.0 

Description 

Determines whether or not a column is set to expand or contract automatically 
depending on the document size. This function fails if the current selection is 
not a table. 

Arguments 

col Num 

col Hum is the column to be sized automatically or fixed width. 
Returns 

Returns true if the column at the given index in the currently selected table is set 
to "autostretch", fal se otherwise. 

dom,makeCeyWidthsConsastent() 

Availability 

Dreamweaver 4.0 

Description 

In the currently selected table, sets the width of each column in the HTML to 
match the currently rendered width of the column. This function fails if the 
current selection is not a table or if the operation was not successful. 

Arguments 

None. 

Returns 

Nothing. 
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dom.removeAySpacers() 



Availability 

Dreamweaver 4.0 

Description 

Removes all spacer images generated by Dreamweaver from the currently selected 
table. This function fails if the current selection is not a table or if the operation 
was not successful. 

Arguments 

None. 

Returns 

Nothing. 

dom,removeSpacerFromCokimn() 

Availability 

Dreamweaver 4.0 

Description 

Removes the spacer image from a specified column and deletes the spacer row if 
there are no more spacer images that Dreamweaver generated. This function fails 
if the current selection is not a table or if the operation was not successful. 

Arguments 

col Num 

col Num is the column from which to remove the spacer image. 

Returns 

Nothing. 
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dom.setColumnAutostretch(5 

Availability 

Dreamweaver 4.0 

Description 

Switches a column between automatically sized or fixed width. If bAutostretch 
is true, the column at the given index in the currently selected table is set to 
"autostretch"; otherwise its set to a fixed width at its current rendered width. 
This function fails if the current selection isn't a table or if the operation 
wasn't successful. 

Arguments 

colNum, bAutostretch 

• CO 1 Hum is the column to be sized automatically or a fixed width. 

• bAutostretch indicates if the column is set to "autostretch" (true) or a fixed 
width (fal se). 

Returns 

Nothing. 

dom,setShowLayoiitTableTabs() 

Availability 

Dreamweaver 4.0 

Description 

Sets the current document to display tabs for layout tables whenever it's in Layout 
view. This function does not force the document into Layout view. 

Arguments 

bShow 

bShow indicates whether or not to display tabs for layout tables when the current 
document is in Layout view. If bShow is true, shows tabs; fal se otherwise. 

Returns 

Nothing. 
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dom.setShowLayoutViewQ 

Availability 

Dreamweaver 4.0 

Description 

Places the current document in Layout view if bShow is true. 

Arguments 

bShow 

bShow is a Boolean that toggles the current document between Layout view and 
Standard view. If bShow is true, the current document switches to Layout view. 

Returns 

Nothing. 

Window functions 

Window functions deal with operations related to the Document window 
and the floating panels. These functions show and hide floating panels, 
determine which part of the Document window has focus, and set the active 
document. For operations related specifically to the Site window, see "Site 
functions" on page 348. 

dofY^getFocusQ 

Availability 

Dreamweaver 3.0 

Description 

Determines the part of the document that is currently in focus. 

Arguments 

None. 

Returns 

One of the following strings: 

• " h e a d " if the HEAD area is active 

• "body" if the BODY or NOFRAMES area is active 

• " frameset " if a frameset or any of its frames is selected 

• " none " if the focus is not in the document (for example, if it's in the Property 
inspector or another floating panel) 

Enabler 

None. 
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dom.getViewQ 

Availability 

Dreamweaver 4.0 

Description 

Determines which view is visible. 

Arguments 

None. 

Returns 

"design", "code", or " spl i t", depending on the visible view. 

dom.getWlndowTstleO 

Availability 

D ream weaver 3 . 0 

Description 

Gets the title of the window that contains the document. 

Arguments 

None. 

Returns 

A string containing the text that appears between the TITLE tags in the document, 
or nothing if the document is not in an open window. 

Enabler 

None. 

dom,se!View() 

Availability 

Dreamweaver 4.0 

Description 

Shows or hides the Design or Code view to produce a design-only, code-only, or 
split view. 

Arguments 

viewString 

vi ewStri ng is the view to produce; it must be one of the following values: 

desi gn", "code", or "spl it". 

Returns 

Nothing. 
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dreamweaver.ge!ActiveWindow(5 

Availability 

Dreamweaver 3.0 

Description 

Gets the document in the active window. 

Arguments 

None. 

Returns 

The document object corresponding to the document in the active window; or, if 
the document is in a frame, the document object corresponding to the frameset. 

Enabler 

None. 

dreamweaver.getDocumentListQ 

Availability 

Dreamweaver 3.0 

Description 

Gets a list of all the open documents. 

Arguments 

None. 

Returns 

An array of document objects, each corresponding to an open Document window. 
If a Document window contains a frameset, the document object refers to the 
frameset, not the contents of the frames. 

Enabler 

None. 
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dreamweaver.gefFloaterVissbiHtyO 

Availability 

Dreamweaver 3.0 

Description 

Checks whether the specified panel or inspector is visible. 

Arguments 

f loaterName 

fl oaterNdme is the name of a floating panel. The built-in panels must be 
referenced using one the following strings: "objects", "properties", 
"launcher", "site files", "site map", "1 i brary ", "ess styles", 
"html styles", "behaviors", "timel ines", "html ", "1 ayers", "frames", 
"tempi ates", "hi story" . If fl oaterName does not match one of the built-in 
p anel names, Dreamweaver searches in the C o n f i g u r a t i o n / F 1 o a t e r s folder 
for a file called "floaterName.htm". 

Returns 

true if the floating panel is visible and frontmost, false otherwise or if 
Dreamweaver cannot find a floating panel with the name floa terName. 

Enabler 

None. 



dreamweaver.geiFocusQ 

Availability 

Dreamweaver 4.0 

Description 

Determines what part of the application is currently in focus. 

Arguments 

bAl 1 owFl oaters 
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Returns 

One of the following strings: 

• "document " if the Document window is in focus. 

• "si t e " if the Site window is in focus. 

• " t e x t V i e w " if the Text view is in focus. 

• " html" if the Code inspector is in focus. 

• f 1 oaterName, if bAl 1 owFl oaters is true and a floating panel has focus, 
where f 1 oaterName is "objects", "properti es ", "1 auncher", "1 i brary ", 
"ess styles", "html styles", "behaviors", "timelines", "layers", 
"frames", "tempi ates", or "hi story". 

• (Macintosh) " none " if neither the Site window nor any Document 
windows are open. 

Enabler 

None. 

dreamweaver.getPrimaryView() 

Availability 

Dreamweaver 4.0 

Description 

Determines which view is visible as the primary (on top) view. 

Arguments 

None. 

Returns 

"design" or " code " , depending on which view is visible or on the top in 
a split view. 

dreamweaver„getSnapDistance() 

Availability 

Dreamweaver 4.0 

Description 

Returns the snapping distance in pixels. 

Arguments 

None. 

Returns 

An integer representing the snapping distance in pixels. The default is 10 pixels; 
0 indicates the Snap feature is off. 
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dreamweaver.min[mszeRestoreAH{) 

Availability 

Dreamweaver 4.0 

Description 

Minimizes (reduces the window to an icon) or restores all windows in 
Dreamweaver. 

Arguments 

bMinimize 

bMinimize is a Boolean value, true indicates that windows should be minimized; 
false indicates that minimized windows should be restored. 

Returns 

Nothing. 

dreamweaver.setActiveWindow() 

Availability 

Dreamweaver 3.0 

Description 

Activates the window containing the specified document. 
Arguments 

documentObject, {bActi v ate Frame} 

• docunientObject is the object at the root of a document's DOM tree (the value 
returned by dreamweaver . getDocumentDOM( )). 

• bActi vateFrame, applicable only if docunientObject is inside a frameset, is 
a Boolean value indicating whether to activate the frame that contains the 
document as well as the window that contains the frameset. 

Returns 

Nothing. 

Enabler 

None. 
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dreamweaver.setRoaterVisabifityO 

Availability 

Dreamweaver 3.0 

Description 

Specifies whether to make a particular floating panel or inspector visible. 
Arguments 

fl oaterName, blsVisible 

• floa terName is the name of a floating panel. The built-in panels must be 
referenced using one the following strings : "objects", "properties", 

"1 auncher", "si te files", "site map", " 1 i bra ry ", "ess styles", 
"html styl es", "behavi ors", "timel i nes", "html ", "1 ayers", "frames", 
"tempi ates", "hi story". If fl oaterName does not match one of the built-in 
panel names, Dreamweaver searches in the Configuration/Floaters folder 
for a file called "floaterName.htm". If Dreamweaver cannot find a floating 
panel with the name fl oaterName, this function has no effect. 

• b Is V i s i b 1 e is a Boolean value indicating whether to make the floating 
panel visible. 

Returns 

Nothing. 

Enabler 

None. 

dreamweaver n setPnrnaryView() 

Availability 

Dreamweaver 4.0 

Description 

Displays the specified view at the top of the Document window. 

Arguments 

viewString 

viewString is the view to bring to the top of the Document window; it can be 
one of the following values: "design" or "code". 

Returns 

Nothing. 
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dreamweaver.setSnapDiStanceQ 

Availability 

Dreamweaver 4.0 

Description 

Sets the snapping distance in pixels (0 to turn it off; default is 1 0 pixels) 

Arguments 

snapDi stance 

snapDi stance is an integer representing the snapping distance in pixels. The 
default is 1 0 pixels. Specify 0 to turn the Snap feature off. 

Returns 

Nothing. 



dreamweaver^showProperfsesQ 

Availability 

Dreamweaver 3.0 

Description 

Makes the Property inspector visible and gives it focus. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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dreamweaver.toggleHoaterQ 

Availability 

Dreamweaver 3.0 

Description 

Shows, hides, or brings to the front the specified panel or inspector. 

Note: This function is meaningful only in the menus.xml file. To show, bring forward, or hide 
a floating panel, use dw.setFloaterVisibility(). 

Arguments 

f loaterName 

f loaterName is the name of the window. If the floating panel name is reference, 
the visible/invisible state of the Reference panel can be updated by the user's 
selection in the Code view. All other panels track the selection all the time, but 
the Reference panel tracks the selection in the Code View only when the user 
invokes tracking. 

Returns 

Nothing. 

Enabler 

None. 

dreamweavenupdateReferenceQ 

Availability 

Dreamweaver 4.0 

Description 

Updates the Reference floating panel. If the Reference floating panel is not visible, 
makes it visible and then updates it. 

Arguments 

None. 

Returns 

Nothing. 
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Deprecated functions 



Deprecated functions work, but have been superseded by newer features in 
Dreamweaver. You should use the newer alternatives, because support for the 
deprecated functions may be withdrawn in future Dreamweaver versions. 

dreamweaver 0 getBehaviorEvent() 

Availability 

Dreamweaver 1.2, deprecated in 2.0 because actions are now chosen 
before events. 

Description 

In a Behavior action file, gets the event that triggers this action. 

Arguments 

None. 

Returns 

A string representing the event. This is the same string that is passed as an 
argument (event) to the canAcceptBehavi or( ) function. 

Example 

The following instance of getBeha vi orEvent ( ) is from the ini ti al i zeUI ( ) 
function in the Drag Layer action file. The role of the following snippet is similar 
to that ofcanAcceptBehavior( ) — that is, it checks whether the selected event 
is appropriate for the selected action. Such a construct is more useful than 
canAcceptBehaviorO, because it lets you offer the user some guidance about 
which events are suitable for calling the selected action. canAcceptBehavi or ( ) 
can make the action unavailable in the Actions pop-up menu only if the user 
chooses an inappropriate event. 

theEvent = dreamweaver . getBehavi orEventC ) . tol_owerCase( ) ; 
CANBEAPPLI ED = (theEvent != "onmousedown " && theEvent != - 
"onmousemove" ) ; 
if ( CANBEAPPLI ED ) { 

[display the Drag Layer UI] 
} else{ 

[display a helpful message that tells the user which events -< 
are appropriate for the Drag Layer action.] 

} 

dreamweaver.getObjectRefsQ 

Availability 

Dreamweaver 1.0 
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Description 

Scans the specified documents for instances of the specified tags (or, if no tags are 
specified, for all tags in the document) and formulates browser-specific references 
to them. This function is equivalent to calling getElementsByTagNameO and 
then calling dreamweaver . get El ementRef ( ) for each tag in the nodel i st. 

Arguments 

NSorlE, sourceDoc, (tagl}, {tag2},...{tagN} 

• NSorlE must be either "NS 4.0"or"IE 4 . 0". The DOM and rules for nested 
references differ in Navigator 4.0 and Internet Explorer 4.0. This argument 
specifies for which browser to return a valid reference. 

• sourceDoc must be "document", "parent", "pa rent . frames [ number] ", 
"parent . frames [ ' frameName' ] ", or a URL. document specifies the 
document that has the focus and contains the current selection, parent 
specifies the parent frameset (if the currently selected document is in a frame), 
and parent . f rameslnumber] and parent. . f rames[ ' frameName' ] specify a 
document that is in a particular frame within the frameset containing the 
current document. If the argument is a relative URL, it is relative to the 
extension file. 

• The third and subsequent arguments, if supplied, are the names of tags (for 
example, "IMG", "FORM", "HR"). 

Returns 

An array of strings, each a valid JavaScript reference to a named instance 
of the requested tag type in the specified document (for example, 
"document .my Layer . document . my Image") for the specified browser. 

• Dreamweaver returns correct references for Internet Explorer for A, AREA, 
APPLET, EMBED, DIV, SPAN, INPUT, SELECT, OPTION, TEXTAREA, OBJECT, and 
IMG tags. 

• Dreamweaver returns correct references for Navigator for A, AREA, APPLET, 
EMBED, LAYER, I LAYER, SELECT, OPTION, TEXTAREA, OBJECT, and IMG tags, and 
for absolutely positioned D I V and SPAN tags. For D I V and SPAN tags that are not 
absolutely positioned, Dreamweaver returns "cannot reference <tag>". 

• Dreamweaver does not return references for unnamed objects. If an object 
does not contain either a NAME or an I D attribute, then Dreamweaver returns 
"unnamed < tag> " . If the browser does not support a reference by name, 
Dreamweaver references the object by index (for example, 

document .my form. a ppl ets[3]). 

• Dreamweaver does return references for named objects contained in unnamed 
forms and layers (for example, document . forms [21 . myCheckbox). 

When the same list of arguments is passed to getObjectTags(),the two 
functions return arrays of the same length and with parallel content. 
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Example 

dreamweaver . getObjectRef s( "NS 4.0", "document", " IMG" ), depending 
on the contents of the active document, might return an array with the 
following items: 

• "document . bul 1 et" 

• "document . 1 ayers[ ' header Layer']. document .header" 

• "document . photo Layer . document . head shot" 

dreamweavef\getObjectTags{) 

Availability 

Dreamweaver 1 .0 

Description 

Scans the specified document for instances of the specified tags or, if no tags are 
specified, for all tags in the document. This function is equivalent to calling 
get El ementsByTagName( ) and then getting outerHTML for each element in the 
nodel i st. 

Arguments 

sourceDoc, {tagl}, {tag2},...{tagNj 

• sourceDoc must be "document", "parent", "parent . f ra mes [ number] ", 
"parent . frames [ ' frameName' ] ", or a URL. document specifies the 
document that has the focus and contains the current selection, parent 
specifies the parent frameset (if the currently selected document is in a frame), 
and parent . f rame$[number] and parent . f rames[ ' frameName' ] specify a 
document that is in a particular frame within the frameset containing the 
current document. If the argument is a relative URL, it is relative to the 
extension file. 

• The second and subsequent arguments, if supplied, are the names of tags (for 
example, "IMG", "FORM", "HR"). 

Returns 

An array of strings, each the HTML source code for an instance of the requested 
tag type in the specified document. 

• If one of the tag arguments is LAY ER, the function returns all LAY ER and 
I LAYER tags and all absolutely positioned DIV and SPAN tags. 

• If one of the tag arguments is INPUT, the function returns all form elements. To 
get a particular type of form element, specify INPUT / TYPE, where TYPE is 
button, text, radio, checkbox, password, textarea, select, hidden, 
reset, or submi t. 

When the same list of arguments is passed togetObjectRefsO, the two 
functions return arrays of the same length. 
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Example 

dreamweaver . getObjectTags ( "document" , " IMG" ), depending on the 
contents of the active document, might return an array with the following items: 

• '<IMG SRC="/images/dot.gif" WIDTH="10" HEIGHT="10" 
NAME="bullet M >' 

• ' < IMG SRC="header.gif" WIDTH="400" HEIGHT="32" NAME=" header") ' 

• '<IMG SRC="971208_nj.jpg" WIDTH="119" HEIGHT="119" 
NAME="headshot">' 

drearnweaver u getSelectSon() 

Availability 

Dreamweaver 2.0, deprecated in 3.0 in favor of dom . getSel ecti on ( ) . 
Description 

Gets the selection in the current document, expressed as byte offsets into the 
document s HTML source code. 

Arguments 

None. 

Returns 

An array containing two integers. The first integer is the byte offset of the 
beginning of the selection; the second integer is the byte offset of the end of the 
selection. If the two numbers are the same, then the current selection is an 
insertion point. 

dreamweaverJjbraryPa!ette n de!eteSe!ectedftern() 

Availability 

Dreamweaver 3.0, deprecated in Dreamweaver 4.0 in favor of using 

dw. as set Pal ette . setSel ectedCategory ( "1 i brary " ), then calling 
dw. as set Pal ette . remove From Fa vori tes. 

Description 

Removes the selected library item from the Library panel and deletes its associated 
LB I file from the Library folder at the root of the current site. Instances of the 
deleted item may still exist in pages throughout the site. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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dreamweaverJsbraryPalette.getSeSectedltemO 



Availability 

Dreamweaver 3.0, deprecated in 4.0 in favor of 

dw. as set Pal ette . getSel ectedltems( ). 

Description 

Gets the path of the selected library item. 

Arguments 

None. 

Returns 

A string containing the path of the library item, expressed as a file:// URL. 

Enabler 

None. 

dreamweaverJibraryPaiette.newFromDocurrsentC) 

Availability 

Dreamweaver 3.0, deprecated in Dreamweaver 4.0 in favor of using 
dw. as set Pal ette . setSel ectedCategory ( "1 i brary " ), then calling 
dw. asset Pal ette. newAsset( ). 

Description 

Creates a new library item based on the selection in the current document. 

Arguments 

bRepl aceCurrent 

bRep 1 aceCurrent is a Boolean value indicating whether to replace the selection 
with an instance of the newly created library item. 

Returns 

Nothing. 

Enabler 

None. 
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dreamweaverJsbraryPaiette.recreateFromDocumentO 

Availability 

Dreamweaver 3.0, deprecated in Dreamweaver 4.0 in favor of 

dw. as set Pal ette . recreate Li bra ryFromDocument ( ). 

Description 

Creates an LB I file for the selected instance of a library item in the 
current document. This function is equivalent to clicking Recreate in the 
Property inspector. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

dreamweaverJibraryPa!ette u renameSe!ectedStem() 

Availability 

Dreamweaver 3.0, deprecated in Dreamweaver 4.0 in favor of using 
dw. as set Pal ette . setSel ectedCa t ego ry( "1 i brary " ), then calling 
dw. as set Pal ette . renameNi ckname( ) . 

Description 

Turns the name of the selected library item into an edit field, allowing the user to 
rename the selection. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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dreamweaver.nodeToOffsetsQ 

Availability 

Dreamweaver 2.0, deprecated in 3.0 in favor of dom . nodeToOf f sets ( ). 
Description 

Gets the position of a specific node in the DOM tree, expressed as byte offsets 
into the document's HTML source code. 

Arguments 

node 

node must be a tag, comment, or range of text that is a node in the tree returned 

by d rea mwea ve r . ge t Document DOM ( ). 

Returns 

An array containing two integers. The first integer is the byte offset of the 
beginning of the tag, text, or comment; the second integer is the byte offset 
of the end of the node. 

Example 

The following code selects the first image object in the current document: 

var theDOM = dreamweaver . getDocumentDOM( "document ") ; 

var thelmg = theDOM . i mages [0] ; 

var offsets = dom. nodeToOf f sets ( thelmg) ; 

dom. set Sel ect ion (off sets [0] , offsets [1] ) ; 



dreamweaver,terYtpSatePatette.getSelectedTempbte() 

Availability 

Dreamweaver 3.0, deprecated in 4.0 in favor of 

dw. asset Pa lette. get Sel ectedltems( ). 

Description 

Gets the path of the selected template. 

Arguments 

None. 

Returns 

A string containing the path of the template, expressed as a file:// URL. 

Enabler 

None. 



462 Chapter 20 



dreamweaver.offsetsToNodeQ 

Availability 

Dreamweaver 2.0, deprecated in 3.0 in favor of dom . of f setsToNode ( ). 
Description 

Gets the object in the DOM tree that completely contains the range of characters 
between the specified begin and end points. 

Arguments 

offsetBegin, offsetEnd 

The arguments are the begin and end points, respectively, of a range of characters, 
expressed as byte offsets into the document's HTML source code. 

Returns 

The tag, text, or comment object that completely contains the specified range 
of characters. 

Example 

The following code displays an alert if the selection is an image: 

var offsets = dreamweaver . getSel ecti on ( ) ; 

var theSel ecti on = dreamweaver . of fsetsToNode( of f sets [0] , -< 

offsets[l]); 

if (theSelection.nodeType = Node . ELEMENT_N0DE && - 
theSel ection . tagName == ' IMG' ) { 

alert('The current selection is an image.'); 

} 

dreamweaver.popupCommandO 

Availability 

Dreamweaver 2.0, deprecated in 3.0 in favor of dreamweaver . runCommand( ). 
Description 

Executes the specified command. To the user, the effect is the same as choosing the 
command from a menu; if a dialog box is associated with the command, it 
appears. This function provides the ability to call a command from another 
extension file. It blocks other edits until the user dismisses the dialog box. 

Nate: This function can be called only within ob j ectTag ( ) or in any script in a command 
or Property Inspector file. 

Arguments 

commandFile 

comma ndFi 1 e is the name of a command file within the Configuration/ 
Commands folder (for example, " Format Tabl e . htm"). 

Returns 

Nothing. 
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dreamweaver.setSeSectionQ 



Availability 

Dreamweaver 2.0, deprecated in 3.0 in favor ofdom.setSelectionO. 
Description 

Sets the selection in the current document. This function can move the 
selection only within the current document; it cannot change the focus to 
a different document. 

Arguments 

offsetBegi n 3 offsetEnd 

The arguments are the begin and end points, respectively, for the new selection, 
expressed as byte offsets into the document's HTML source code. If the two 
numbers are the same, the new selection is an insertion point. If the new selection 
is not a valid HTML selection, it is expanded to include the characters in the first 
valid HTML selection. For example, if offsetBegin and offsetEnd define the 
range SRC=" my Image . gi f " within < I MG SRC="my Image . gi f ">, the selection 
expands to include the entire IMG tag. 

Returns 

Nothing. 

drearriweaver H temp!atePalette,de!eteSeIectedTerrsplate() 

Availability 

Dreamweaver 3.0, deprecated in Dreamweaver 4.0 in favor of using 
dw.assetPalette.setSel ec ted Category ( "tempi ates" ), then calling 
dw. as set Pal ette . remove From Fa vori tes( ). 

Description 

Deletes the selected template from the templates folder. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 
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dreamweaver.templatePalette.renameSelectedIemplate() 



Availability 

Dreamweaver 3.0, deprecated in Dreamweaver 4.0 in favor of using 
dw. as set Pal ette . setSel ectedCa t ego ry ( "tempi ates" ), then calling 
dw. as set Pal ette . renameNi ckname( ) . 

Description 

Turns the name of the selected template into an edit field, allowing the user to 
rename the selection. 

Arguments 

None. 

Returns 

Nothing. 

Enabler 

None. 

Enabler functions determine whether to enable menu items based on whether 
Dreamweaver can perform specific operations in the current context. The 
function specifications describe the general circumstances under which each 
function returns true. However, the descriptions are not intended to be 
comprehensive and may exclude some cases in which the function would 
return fal se. 

dom.canAlign() 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform an Align Left, Align Right, Align Top, 
or Align Bottom operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether two or more layers or hotspots are selected. 
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dom.canAppIylemplateO 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform an Apply To Page operation. This 
function is valid only for the active document. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the document is not a library item or a 
template, and that the selection is not within the NO FRAMES tag. 

domxanArrangeQ 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a Bring to Front or Move to 
Back operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether a hotspot is selected. 

domxanCHpCopyTextQ 

Availability 

Dreamweaver 3-0 

Description 

Checks whether Dreamweaver can perform a Copy as Text operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the selection is a range (that is, not an 
insertion point). 



466 Chapter 20 



dorTLcanCh'pFasteQ 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a Paste operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the clipboard contains any content that can 
be pasted into Dreamweaver. 

domxanCHpPasteTextQ 

Availability 

D ream weaver 3 . 0 

Description 

Checks whether Dreamweaver can perform a Paste as Text operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the clipboard contains any content that can 
be pasted ino Dreamweaver as text. 

domxanCorwertLayersToTab!e{) 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a Convert Layers to Table operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether all content in the BODY of the document is 
contained within layers. 
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domxanConvertTabSesToLayersQ 



Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a Convert Tables to Layers operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether all the content in the BODY of the document is 
contained within tables, and the document is not based on a template. 

dom,canDecreaseCoSspan() 

Availability 

D ream weaver 3 . 0 

Description 

Checks whether Dreamweaver can perform a Decrease Colspan operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the current cell has a COLSPAN attribute, and 
whether that attribute's value is greater than or equal to 2. 

domxanDecreaseRowspanO 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a Decrease Rowspan operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the current cell has a ROWSPAN attribute, and 
whether that attribute's value is greater than or equal to 2. 
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dom.canDeleteIableCoIumn{) 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a Delete Column operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the insertion point is inside a cell, or if a cell 
or column is selected. 

domxanDeieteTableRowQ 

Availability 

D ream weaver 3 . 0 

Description 

Checks whether Dreamweaver can perform a Delete Row operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the insertion point is inside a cell, or if a cell 
or row is selected. 

dorY^canEditMoFramesContentO 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform an Edit No Frames Content 
operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the current document is a frameset or within 
a frameset. 
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dom.canlncreaseCoSspan() 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform an Increase Colspan operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether there are any cells to the right of the 
current cell. 

domxanhicreaseRowspanQ 

Availability 

D ream weaver 3 . 0 

Description 

Checks whether Dreamweaver can perform an Increase Rowspan operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether there are any cells below the current cell. 

dom.canlnsertTabSeColumns() 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform an Insert Column(s) operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the selection is inside a table. This function 
returns fa 1 se if the selection is an entire table. 
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dom.canlnsertTabSeRowsQ 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform an Insert Row(s) operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the selection is inside a table. This function 
returns f a 1 se if the selection is an entire table. 

domxanMakeNewEdBtableRegionQ 

Availability 

D ream weaver 3 . 0 

Description 

Checks whether Dreamweaver can perform a New Editable Region operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the current document is a template 
(.dwt) file. 

dorY^canMarkSe!ectionAsEdstabIe{) 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a Mark Selection as Editable 
operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether there is a selection, and whether the current 
document is a template (.dwt) file. 
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dom.canMergeTableCellsQ 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a Merge Cells operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the selection is a rectangular grouping of 
table cells. 

dom,canPSayPlugsn() 

Availability 

D ream weaver 3 . 0 

Description 

Checks whether Dreamweaver can perform a Play operation. This function is 
valid only for the active document. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the selection can be played with a plugin. 

domxanRedoQ 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a Redo operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether any steps remain to redo. 
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dom.canRemoveEdstableRegionQ 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform an Unmark Editable 
Region operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the current document is a template. 

domxanSdectTableQ 

Availability 

D ream weaver 3 . 0 

Description 

Checks whether Dreamweaver can perform a Select Table operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the insertion point or selection is 
within a table. 

domxanSetLinkHref() 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can change the link around the current selection or 
create one if necessary. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the selection is an image, text, or an insertion 
point inside a link. A text selection is defined as a selection for which the text 
Property inspector would appear. 
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dom.canShowListPropertfesDiaSogO 

Availability 

Dreamweaver 3.0 

Description 

Determines whether Dreamweaver can show the List Properties dialog box. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the selection is within an LI tag. 

Enabler 

None. 

dom.canSpiitFrame() 

Availability 

D ream weaver 3 . 0 

Description 

Checks whether Dreamweaver can perform a Split Frame [Left | Right | Up | 
Down] operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the selection is within a frame. 

domxanSpHtTableCelSQ 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a Split Cell operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the insertion point is inside a table cell or the 
selection is a table cell. 
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dom.canStopPIugmQ 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a Stop operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the selection is currently being played 
with a plugin. 

domxanUndoQ 

Availability 

D ream weaver 3 . 0 

Description 

Checks whether Dreamweaver can perform an Undo operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether any steps remain to undo. 

dom.hasTracinglrnageQ 

Availability 

Dreamweaver 3.0 

Description 

Checks whether the document has a tracing image. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the document has a tracing image. 
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dreamweaver.assetFaSettexanEcHtQ 



Availability 

Dreamweaver 4.0 

Description 

Enables menu items in the Assets panel for editing. 

Arguments 

None. 

Returns 

Returns true if the asset can be edited or fa 1 se if not. Will return f a 1 se for 
colors and URLs in the Site list, and will return fal se for a multiple selection of 
colors and URLs in the Favorites list. 

dreamweaver D assetPaIette B can^nsertOrAppIy() 

Availability 

Dreamweaver 4.0 

Description 

Determines if the selected elements can be inserted or applied. Returns true or 
f a 1 se so the menu items can be enabled or disabled for insertion or application. 

Arguments 

None. 

Returns 

Returns f a 1 se if the current page is a template, and the current category is 
"Templates". Returns fal se if no document is open. Returns fal se if a library 
item is selected in the document and the current category is "Library". Otherwise 
returns true. 

dreamweaver D canCHpCopy() 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a Copy operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether there is anything selected that can be copied 
to the clipboard. 
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dreamweaver.canCHpCutQ 



Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a Cut operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether there is anything selected that can be cut to 
the clipboard. 

dreamweaver.canCHpPasteQ 

Availability 

D ream weaver 3 . 0 

Description 

Checks whether Dreamweaver can perform a Paste operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the clipboard contains any content that can 
be pasted into the current document or the active pane in the Site window; or, on 
the Macintosh, an edit field in a floating panel or dialog box. 

dreamweaver 0 canDeieteSelect^on() 

Availability 

Dreamweaver 3-0 

Description 

Checks whether Dreamweaver can delete the current selection. Depending on 
the window that has focus, the deletion may occur in the Document window or 
the Site window; or, on the Macintosh, in an edit field in a dialog box or 
floating panel. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the selection is a range (that is, not an 
insertion point). 
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dreamweaver.canExportCSSQ 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform an Export CSS Styles operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the document contains any class styles 
defined in the HEAD. 

d reamweaverxan Fb nd NextQ 

Availability 

D ream weaver 3 . 0 

Description 

Checks whether Dreamweaver can perform a Find Next operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether a search pattern has already been established. 

dreamweaver.canQpen!nFrame() 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform an Open in Frame operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the selection or insertion point is 
within a frame. 
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dreamweaver.canPlayRecordedCommand() 

Availability 

Dreamweaver 3.0 

Description 

Determines whether Dreamweaver can perform a Play Recorded Command 
operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether there is an active document and a previously 
recorded command that can be played. 

d reamweaver.can Red o() 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a Redo operation in the 
current context. 

Arguments 

None. 

Returns 

A Boolean value indicating whether any operations can be undone. 

dreamweaver 0 canRevertDocument() 

Availability 

Dreamweaver 3-0 

Description 

Checks whether Dreamweaver can perform a Revert (to the last-saved version) 
operation. 

Arguments 

documentObject 

documentObject is the object at the root of a documents DOM tree (the value 
returned by dreamwea ver . getDocumentDOM( )). 

Returns 

A Boolean value indicating whether the document is in an unsaved state and a 
saved version of the document exists on a local drive. 
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dreamweaver.canSaveAHQ 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a Save All operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether one or more unsaved documents are open. 

dreamweaverxanSaveDocumentO 

Availability 

D ream weaver 3 . 0 

Description 

Checks whether Dreamweaver can perform a Save operation on the 
specified document. 

Arguments 

documentObject 

documentObject is the object at the root of a documents DOM tree (the value 
returned by dreamwea ver . getDocumentDOM( )). 

Returns 

A Boolean value indicating whether the document has any unsaved changes. 

dreamweaver D canSaveDocumentAsTempiate() 

Availability 

D ream weaver 3 . 0 

Description 

Checks whether Dreamweaver can perform a Save As Template operation on the 
specified document. 

Arguments 

documentObject 

documentObject is the object at the root of a documents DOM tree (the value 
returned by dreamweaver . getDocumentDOM( )). 

Returns 

A Boolean value indicating whether the document can be saved as a template. 
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dreamweaver.canSaveFramesetQ 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a Save Frameset operation on the 
specified document. 

Arguments 

documentObject 

documentObject is the object at the root of a documents DOM tree (the value 
returned by dreamwea ver . getDocumentDOM( )). 

Returns 

A Boolean value indicating whether the document is a frameset with 
unsaved changes. 

dreamweaver.canSaveFramesetAsQ 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a Save Frameset As operation on the 
specified document. 

Arguments 

documentObject 

documentObject is the object at the root of a documents DOM tree (the value 
returned by dreamwea ver . getDocumentDOM( )). 

Returns 

A Boolean value indicating whether the document is a frameset. 

dreamweaver D canSe!ectAy() 

Availability 

Dreamweaver 3-0 

Description 

Checks whether Dreamweaver can perform a Select All operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether a Select All operation can be performed. 
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dreamweaver.canShowFandDiaiogO 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a Find operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether a Site window or a Document window is 
open. This function returns fal se when the selection is in the HEAD. 

dreamweaverxanUndoQ 

Availability 

D ream weaver 3 . 0 

Description 

Checks whether Dreamweaver can perform an Undo operation in the 
current context. 

Arguments 

None. 

Returns 

A Boolean value indicating whether any operations can be undone. 

dreamweaverJsReeordmgQ 

Availability 

Dreamweaver 3.0 

Description 

Reports whether Dreamweaver is currently recording a command. 

Arguments 

None. 

Returns 

A Boolean value indicating whether Dreamweaver is recording a command. 
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dreamweaver.htrnSStylePalette.canEditSeIection() 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can edit, delete, or duplicate the selection in the 
HTML Styles panel. 

Arguments 

None. 

Returns 

A Boolean value. This function returns fa 1 se if no style is selected or if one of the 
"clear" styles is selected. 

dreamweaver D tsmeHnelnspector B canAddFrame() 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform an Add Frame operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the Timelines panel has any animation bars 
or behaviors. 

dreamweaver 0 tsmeHnelnspector 0 canAddKeyFrame() 

Availability 

Dreamweaver 3-0 

Description 

Checks whether Dreamweaver can perform an Add Keyframe operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the selection in the Timelines panel is part of 
an animation bar. 
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dreamweaver.timeHnelnspectorxanChangeObject{) 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a Change Object operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the selection in the Timelines panel is part of 
an animation bar. 

dreamweaver.t?meHne^nspectorxanRemoveBehavlor(} 

Availability 

D ream weaver 3 . 0 

Description 

Checks whether Dreamweaver can perform a Remove Behavior operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the selection in the Timelines panel is 
a behavior. 

dreamweaver H tsmeHne^nspectorxanRernoveFrame{) 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a Remove Frame operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the Timelines panel has any animation bars 
or behaviors. 
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dreamweaver.timeHnelnspectorxanRernoveKeyFrame() 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a Remove Keyframe operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the current frame in the Timelines panel 
is a keyframe. 

dreamweaver.t?meHne^nspectorxanRemoveObject() 

Availability 

D ream weaver 3 . 0 

Description 

Checks whether Dreamweaver can perform a Remove Object operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the Timelines panel has any animation bars. 

site.browseDocurnentC) 

Availability 

Dreamweaver 4.0 

Description 

Opens all selected documents in a browser window, as in the Preview in 
Browser command. 

Arguments 

browserName 

browserName is the name of a browser as defined in the Preview in Browser 
preferences. If omitted, this argument defaults to the user's primary browser. 

Returns 

Nothing. 
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sitexanAddLinkQ 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform an Add Link to [Existing File | New 
File] operation. 

Arguments 

None. 

Returns 

A Boolean value indicating that the selected document in the site map is an 
HTML file. 

siie.canChangeLinkQ 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a Change Link operation. 

Arguments 

None. 

Returns 

A Boolean value indicating that an HTML or Flash file links to the selected file in 
the site map. 
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site.canCheck!n() 

Availability 

Dreamweaver 3.0 

Description 

Determines whether Dreamweaver can perform a Check In operation. 

Arguments 

siteOrURL 

s 1 teOrURL must be the keyword "site", indicating that the function should act 
on the selection in the Site window, or the URL for a single file. 

Returns 

A Boolean value indicating whether all of the following conditions are true: 

• A remote site has been defined. 

• If a Document window has focus, the file has been saved in a local site; or, if the 
Site window has focus, one or more files or folders is selected. 

• Check in/check out is turned on. 

sitexanCheckQutQ 

Availability 

Dreamweaver 3.0 

Description 

Determines whether Dreamweaver can perform a Check Out operation on the 
specified file or files. 

Arguments 

siteOrURL 

s i teOrURL must be the keyword "si te ", indicating that the function should act 
on the selection in the Site window, or the URL for a single file. 

Returns 

A Boolean value indicating whether all of the following conditions are true: 

• A remote site has been defined. 

• If a Document window has focus, the file is part of a local site and is not 
already checked out; or, if the Site window has focus, one or more files or 
folders is selected and at least one of the selected files is not already 
checked out. 

• Check in/check out is turned on. 
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sitexanConnectQ 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can connect to the remote site. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the current remote site is an FTP site. 

sitexanFmdUnkSoureeO 

Availability 

D ream weaver 3 . 0 

Description 

Checks whether Dreamweaver can perform a Find Link Source operation. 

Arguments 

None. 

Returns 

A Boolean value indicating that the selected link in the site map is not the 
home page. 

site.canGetQ 

Availability 

Dreamweaver 3.0 

Description 

Determines whether Dreamweaver can perform a Get operation. 

Arguments 

siteOrURL 

s i teOrURL must be the keyword "si te ", indicating that the function should act 
on the selection in the Site window, or the URL for a single file. 

Returns 

If the argument is "site", Boolean value indicating whether one or more files or 
folders is selected in the Site window and a remote site has been defined. If the 
argument is a URL, a Boolean value indicating whether the document belongs to 
a site for which a remote site has been defined. 
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sitexanLocateSnSsteQ 

Availability 

Dreamweaver 3.0 

Description 

Determines whether Dreamweaver can perform a Locate in Local Site or Locate in 
Remote Site operation (depending on the argument). 

Arguments 

1 ocal OrRemote, siteOrURL 

• / ocal Or Remote must be either "1 ocal " or " remote". 

• s / teOrilRL must be the keyword "site", indicating that the function should 
act on the selection in the Site window, or the URL for a single file. 

Returns 

One of the following values: 

• If the first argument is "local " and the second argument is a URL, a Boolean 
value indicating whether the document belongs to a site. 

• If the first argument is " remote " and the second argument is a URL, a Boolean 
value indicating whether the document belongs to a site for which a remote 
site has been defined, and, if the server type is Local/Network, whether the 
drive is mounted. 

• If the second argument is "site", a Boolean value indicating whether both 
panes contain site files (not the site map) and whether the selection is in the 
opposite pane from the argument. 

sitexanyakeEcHtabteQ 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a Turn Off Read Only operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether one or more of the selected files is locked. 
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sitexanMakeNewFileOrFoSderC) 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a New File or New Folder operation 
in the Site window. 

Arguments 

None. 

Returns 

A Boolean value indicating whether any files are visible in the selected pane of the 
Site window. 



siie.canOpenQ 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can open the files or folders that are currently 
selected in the Site window. 

Arguments 

None. 

Returns 

A Boolean value indicating whether any files or folders are selected in the 
Site window. 
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site.canPutQ 

Availability 

Dreamweaver 3.0 

Description 

Determines whether Dreamweaver can perform a Put operation. 

Arguments 

siteOrURL 

s 1 teOrURL must be the keyword "site", indicating that the function should act 
on the selection in the Site window, or the URL for a single file. 

Returns 

If the argument is " si te ", a Boolean value indicating whether any files or folders 
are selected in the Site window and a remote site has been defined. If the 
argument is a URL, a Boolean value indicating whether the document belongs to 
a site for which a remote site has been defined. 

sitexanRecreateCacheQ 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a Recreate Site Cache operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the Use Cache To Speed Link Updates option 
is enabled for the current site. 
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site.canRefreshQ 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a Refresh [Local | Remote] operation. 

Arguments 

1 ocal OrRemote 

1 ocal Or Remote must be either "1 ocal " or " remote". 
Returns 

true if 1 ocal OrRemote is "1 ocal otherwise, a Boolean value indicating 
whether a remote site has been defined. 

site.canRemoveUnkQ 

Availability 

Dreamweaver 3.0 

Description 

Checks whether Dreamweaver can perform a Remove Link operation. 

Arguments 

None. 

Returns 

A Boolean value indicating that an HTML or Flash file links to the selected file in 
the site map. 

sitexanSetLayout() 

Availability 

Dreamweaver 3.0 

Description 

Determines whether Dreamweaver can perform a Layout operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the site map is visible. 
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sitexanSeIectAHCheckedOutF§Ses() 

Availability 

Dreamweaver 4.0 

Description 

Determines whether the current working site has check in/check out enabled. 

Arguments 

None. 

Returns 

A Boolean value; true if the site allows check in/check out, otherwise fal se. 

SitexanSeSectNewerQ 

Availability 

D ream weaver 3 . 0 

Description 

Determines whether Dreamweaver can perform a Select Newer [Remote | Local] 
operation. 

Arguments 

1 ocdl OrRemote 

1 ocal Or Remote must be either "1 ocal " or " remote". 
Returns 

A Boolean value indicating whether the document belongs to a site for which a 
remote site has been defined. 

site.canShowPageTitlesO 

Availability 

D ream weaver 3 . 0 

Description 

Determines whether Dreamweaver can perform a Show Page Titles operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the site map is visible. 
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sitexanSynchromzeQ 

Availability 

Dreamweaver 3.0 

Description 

Determines whether Dreamweaver can perform a Synchronize operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether a remote site has been defined. 

sitexanUndoCheckOutO 

Availability 

D ream weaver 3 . 0 

Description 

Determines whether Dreamweaver can perform an Undo Checkout operation. 

Arguments 

siteOrURL 

s 1 teOrURL must be the keyword "site", indicating that the function should act 
on the selection in the Site window, or the URL for a single file. 

Returns 

A Boolean value indicating whether the specified file or at least one of the selected 
files is checked out (by any user). 

sitacanViewAsRootQ 

Availability 

D ream weaver 3 . 0 

Description 

Determines whether Dreamweaver can perform a View as Root operation. 

Arguments 

None. 

Returns 

A Boolean value indicating whether the specified file is an HTML or Flash file. 
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site^SelectAIICheckedOutFilesQ 

Availability 

Dreamweaver 4.0 

Description 

Selects all files in the local site that have been checked out. 

Arguments 

None. 

Returns 

Nothing. 
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setListBoxKind() 282 
setListTag() 282 
setLoop() 409 
setMenuText() 50 
SetNote() 127 

setPreventLayerOverlaps() 417 

setPrimaryView() 453 

setRulerOrigin() 436 

setRulerUnits() 437 

setSelectedBehavior() 226 

setSelectedNode() 346 

setSelection() 

dom.setSelection() 347 
dreamweaver.setSelection() 464 
site.setSelection() 370 

setShowDependents() 430 

setShowFrameBorders() 418 

setShowGrid()4l8 

setShowHeadView()4l8 

setShowHiddenFiles() 430 

setShowHighlightInvalidHTML() 419 

setShowImageMaps() 419 

setShowInvisibleElements() 419 

setShowLayerBorders() 420 

setShowLayoutTableTabs() 446 

setShowLayoutView() 447 

setShowLineNumbers() 420 

setShowPageTitles() 430 

setShowRulers() 420 

setShowStatusBar() 427 

setShowTableBorders() 421 

setShowToolbar() 421 



setShowToolTips() 431 
setShowTracingImage() 422 
setShowWordWrap() 422 
setSnapDistance() 454 
setSnapToGrid() 422 
setTableCellTag() 400 
setTableColumns() 400 
setTableRows() 401 
setTextAlignment() 283 
setTextFieldKind() 283 
setTimeout() 14 

in floating panels 83 

use with FWLaunch 1 06 
setTracinglmageOpacityO 438 
setTracingImagePosition() 437 
setUndoState() 300 
setUpComplexFindO 261 
setUpComplexFindReplace() 262 
setUpFindO 263 
setUpFindReplace() 264 
setView() 448 
showAboutBox() 288 
showConnectionMgrDialog() 158 
showFindDialog() 265 
showFindReplaceDialog() 265 
showFontColorDialog() 284 
showGridSettingsDialog() 440 
showInsertTableRowsOrColumnsDialog() 40 1 
showListPropertiesDialog() 282 
showPagePropertiesDialog() 290 
showPreferencesDialogQ 288 
showProperties() 454 
showQuickTagEditor() 335 
showReportsDialog() 336 
showResultset() 158 
showSPResultset() 159 
showSPResultsetNamedParamsO 160 
shutdown commands 23 
Shutdown folder 23 
site object 

methods of 206 

properties of 1 8 
site.addLinkToExistingFile() 349 
site.addLinkToNewFile() 349 
site.browseDocumentQ 485 
site.canAddLinkToFileO 486 
site.canChangeLink() 486 
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site.canChecklnQ 487 
site.canCheckOutO 487 
site.canConnect() 488 
site.canFindLinkSource() 488 
site.canGet() 488 
site.canLocateInSite() 489 
site.canMakeEditable() 489 
site.canMakeNewFileOrFolder() 490 
site.canOpenQ 490 
site.canPut() 491 
s ite . can Recreate Cache () 4 9 1 
site.canRefresh() 492 
site.canRemoveLink() 492 
site.canSelectAllCheckedOutFiles() 493 
site.canSelectNewer() 493 
site.canSetLayout() 492 
site.canSynchronize() 494 
site.canUndoCheckOutQ 494 
site.canViewAsRoot() 494 
site.changeLink() 350 
site.changeLinkSitewide() 350 
site.checkln() 351 
site.checkLinks() 351 
site.checkOut() 352 
site.checkTargetBrowsers() 352 
site.defineSites() 353 
site. delete SelectionQ 353 
site.findLinkSource() 354 
site.getQ 355 

site.getCheckOutUser() 355 
site.getCheckOutUserForFile() 356 
site.getConnectionState() 356 
site.getCurrentSite() 357 
site.getFocus() 357 
site.getLinkVisibility() 358 
site.getSelection() 358 
site.getShowDependents() 428 
site.getShowHiddenFiles() 428 
site.getShowPageTitles() 429 
site.getShowToolTips() 429 
site.getSites() 359 
site.invertSelection() 359 
site.locateInSite() 354 
site.makeEditableO 359 
site. makeNewDream weaver File() 360 
site.makeNewFolder() 360 
site.newHomePage() 361 



site. newS ite () 361 

site.open() 362 

site.put() 362 

site.recreateCache() 363 

site.refresh() 363 

site. remotels Valid () 364 

site.removeLink() 364 

site.renameSelection() 365 

site.saveAsImage() 365 

site.selectAU() 366 

site.SelectAllCheckedOutFiles() 495 

site.selectHomePage() 366 

site.selectNewer() 367 

site.setAsHomePage() 367 

site.setConnectionState() 368 

site.setCurrentSite() 368 

site.setFocus() 369 

site.setLayout() 369 

site.setLinkVisibility() 370 

site.setSelection() 370 

site.setShowDependents() 430 

site.setShowHiddenFiles() 430 

site.setShowPageTitles() 430 

site.setShowToolTips() 431 

site. synchronize () 371 

site.undoCheckOut() 371 

site.viewAsRoot() 372 

snapTracingImageToSelection() 438 

splitFrame() 267 

splitTableCell() 402 

SQL statements 

getting columns from 1 47, 1 48 
showing results of 158 

startBlock() 68 

startDebugger() 307 

startOfDocument() 315, 385 

startOfLine() 315, 386 

startRecording() 294 

startup commands 23 

Startup folder 23 

status codes 1 37 

statusCode property 1 37 

stopAllPlugins() 439 

stopPlugin() 439 

stopRecording() 294 
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stored procedures 146 

getting columns from 153, 154 
getting parameters for 155 
showing results of 159, 160 

string object 14 

stripTagQ 334 

submit object 14 

SWFFile.createFile() 110 

SWFFile.getNaturalSize() 111 

SWFFile.getObjectTypeQ 112 

SWFFile.readFile() 113 

synchronize() 371 

synchronizeDocument() 387 

T 

tables 156 

getting columns of 149 
tag object 20 
tagName property 20 
text (field) object 14 
text node 22 
text object 22 
textarea object 14 
toggleFloater() 455 
topPage() 386 
translated attributes 

finding in tags 20 
Tree Control Content, Manipulating 28 
Tree controls 24 
typeof operator 129 

y 

undo() 

dom.undoQ 292 

dreamweaver.undo() 294 
undoCheckOut() 371 
unescape() 14 
updateCurrentPage() 326 
updatePages() 327 
updateReference() 455 
URL property 19 
user names 156 
useTranslatedSource() 433 



validateFireworksQ 106 
versioning 18 
view tables 157 
viewAsRoot() 372 

w 

W3C14 

window object 14 
windowDimensions() 59 

in behavior actions 98 

in menu commands 50 

in object files 35 

in regular commands 42 
wrapSelectionQ 387 
wrapTag() 335 
writeQ 136 
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